Module 1a: Installing VS Code

Your Code Editor for Water Modelling¶

Time required: 15-20 minutes
Prerequisites: Module 0 (Introduction)
What you’ll do: Install and explore Visual Studio Code

What is VS Code?¶

Visual Studio Code (VS Code) is a free text editor designed for writing code. Think of it like Microsoft Word, but for programming instead of documents.

Why VS Code?¶

Why Not Just Use Notepad or a Simple Text Editor?¶

You could write Python in Notepad, but VS Code offers:

• Syntax highlighting — Different parts of code appear in different colors, making it easier to read

• Auto-completion — Suggests code as you type, reducing typos

• Error detection — Shows problems before you run the code

• Integrated terminal — Run your scripts without leaving the editor

• File explorer — Navigate your project files easily

These features save time and reduce frustration, especially when learning.

Step 1: Download VS Code¶

Go to the official VS Code website at https://code.visualstudio.com/ and click the Download button. The website automatically detects your operating system and offers the correct version.

Tip: If you need a different version (e.g., 32-bit Windows or a specific Linux distribution), click the small dropdown arrow next to the download button.

Step 2: Install VS Code¶

Follow the official installation guide for your operating system:

The installation process takes just a few minutes. The official guides include troubleshooting tips if you encounter any issues.

Tip: Windows users: During installation, we recommend checking the options to “Add to PATH” and “Add ‘Open with Code’ to context menu” — these make VS Code easier to use later.

Step 3: Launch and Explore VS Code¶

Open VS Code:

• Windows: Search for “Visual Studio Code” in the Start menu

• macOS: Open from Applications or use Spotlight (Cmd+Space, type “Visual Studio Code”)

• Linux: Search in your application menu

The VS Code Interface¶

When VS Code opens, you’ll see several areas:

┌─────────────────────────────────────────────────────────────┐
│  Menu Bar (File, Edit, View, etc.)                         │
├────────┬────────────────────────────────────────────────────┤
│        │                                                    │
│ Side   │              Editor Area                           │
│ Bar    │     (where you write and view code)                │
│        │                                                    │
│ Icons  │                                                    │
│        │                                                    │
├────────┴────────────────────────────────────────────────────┤
│  Panel (Terminal, Output, Problems)                         │
├─────────────────────────────────────────────────────────────┤
│  Status Bar                                                 │
└─────────────────────────────────────────────────────────────┘

Key Areas to Know¶

Note: Don’t worry about memorizing these now. You’ll learn them naturally as you use VS Code.

Step 4: Verify Your Installation¶

Let’s make sure everything works.

Open the Terminal in VS Code¶

1. In VS Code, go to View → Terminal (or press Ctrl+`)

2. A terminal panel should appear at the bottom of the window

This integrated terminal is where you’ll run Python scripts later. For now, just verify it opens.

Checkpoint: Is VS Code Working?¶

✅ VS Code opens without errors
✅ You can see the Explorer, Editor, and Terminal areas
✅ The terminal opens when you go to View → Terminal

If all three are checked, your installation is successful!

Optional: Recommended Settings for Beginners¶

VS Code works great out of the box, but here are a few settings that make it friendlier for beginners.

Enable Auto-Save¶

Never lose work because you forgot to save:

1. Go to File → Preferences → Settings (or Ctrl+, / Cmd+, on Mac)

   • On macOS, this is Code → Settings → Settings

2. Search for “auto save”

3. Set Files: Auto Save to afterDelay

Adjust Font Size (if needed)¶

1. Go to File → Preferences → Settings (on macOS: Code → Settings → Settings)

2. Search for “font size”

3. Adjust Editor: Font Size (default is 14)

Choose a Theme (Optional)¶

1. Go to File → Preferences → Theme → Color Theme (on macOS: Code → Settings → Theme → Color Theme)

2. Try different themes — popular choices:

   • Dark+ (default dark theme)

   • Light+ (default light theme)

   • Many more available as extensions

Why VS Code for Water Modelling?¶

As a water modeller, you might wonder why you need a code editor at all. Here’s how VS Code fits into your workflow:

Current Workflow (Without Python)¶

Excel → Manual calculations → Copy to report → Repeat for each dataset

Future Workflow (With Python + VS Code)¶

Write script once in VS Code → Run on any dataset → Results + plots generated automatically

What You’ll Do in VS Code¶

• Write Python scripts to analyze hydrological data

• Run scripts using the integrated terminal

• Debug errors with helpful error messages and highlighting

• Manage projects with multiple related files

• Use Jupyter notebooks for interactive analysis (after installing the extension)

Example: What Your VS Code Will Look Like¶

Imagine analyzing discharge data:

┌─────────────────────────────────────────────────────────────┐
│ my-water-project                                            │
├────────┬────────────────────────────────────────────────────┤
│ Files  │  analyze_discharge.py                              │
│        │  ─────────────────────────────────────────────     │
│ 📁 data│  import pandas as pd                               │
│   └─ discharge.csv│  import matplotlib.pyplot as plt        │
│ 📄 analyze_discharge.py│                                    │
│ 📄 pyproject.toml│  df = pd.read_csv('data/discharge.csv')  │
│        │  Q_mean = df['discharge'].mean()                   │
│        │  print(f"Mean Q: {Q_mean:.2f} m³/s")               │
├────────┴────────────────────────────────────────────────────┤
│ Terminal                                                    │
│ $ uv run analyze_discharge.py                               │
│ Mean Q: 45.23 m³/s                                          │
└─────────────────────────────────────────────────────────────┘

You’ll get here soon!

Troubleshooting¶

“VS Code won’t install” (Windows)¶

• Try running as Administrator: Right-click the installer → “Run as administrator”

• Check disk space: VS Code needs about 500 MB

• Antivirus interference: Temporarily disable antivirus during installation

• Work computer restrictions: Contact your IT department for help

“VS Code won’t open” (macOS)¶

• Gatekeeper warning (“App can’t be opened because it is from an unidentified developer”): Right-click (or Control-click) the VS Code app and choose Open, then click Open in the dialog. You only need to do this once.

• Move to Applications folder: Make sure you’ve moved VS Code from your Downloads folder to the Applications folder. Drag the VS Code icon to Applications in Finder.

• Work computer restrictions: Contact your IT department for help

“VS Code is slow to start”¶

• First launch is always slower (it’s setting things up)

• Subsequent launches should be faster

• If consistently slow, try disabling extensions you don’t use

“I can’t find VS Code after installing” (Windows)¶

• Search for “Visual Studio Code” in the Start menu (not just “VS Code”)

• Check your desktop for a shortcut

• Look in: C:\Users\YourName\AppData\Local\Programs\Microsoft VS Code

“The terminal won’t open”¶

• Try View → Terminal from the menu bar

• Or press Ctrl+` (the backtick key, usually above Tab) or Cmd+` on Mac

• If still not working, try restarting VS Code

Learn More (Optional)¶

If you want to explore VS Code further, here are excellent official resources:

Note: You don’t need to watch these now. VS Code is intuitive enough to learn as you go. These resources are here if you want to go deeper.

Summary¶

In this module, you:

✅ Learned what VS Code is and why we use it
✅ Downloaded and installed VS Code
✅ Explored the main interface areas
✅ Verified your installation works
✅ (Optionally) Configured beginner-friendly settings

What’s Next?¶

VS Code by itself doesn’t understand Python—it’s just a text editor. In the next module, we’ll install the Python extension that gives VS Code superpowers for Python development:

• Syntax highlighting for Python code

• IntelliSense (smart code suggestions)

• Error detection

• Debugging capabilities

• Jupyter notebook support

Ready? Continue to Module 1b: Python Extension Setup