5  Editors

Motivation and scope

Note: This is a fast-track guide designed to get macOS users up and running with Visual Studio Code (VS Code). A more comprehensive discussion of editors, versioning integration, and other workflow optimizations will be developed in the future.

When writing an essay, we typically turn to word processors like Microsoft Word or Google Docs. When writing code—or, as in Chapter 7, typesetting mathematics in \(\LaTeX\)—we use a text editor. While we could technically write code in basic applications like Apple’s TextEdit, Windows Notepad, or GNOME’s Gedit, modern scientific computing relies on Integrated Development Environments (IDEs) equipped with syntax highlighting, autocomplete features, file and versioning management, terminal integration, and debugging tools. In this section, we focus on Visual Studio Code (VS Code), a free, popular, and highly extensible editor maintained by Microsoft.

Core concepts

Coming soon

Workspaces (not Files)

VS Code is designed around workspaces. Rather than double-clicking a single file in our file browser (like opening an isolated script calculations.py or individual assignment homework.tex), we should always open entire directories containing our projects. To do this, we open VS Code and navigate to File > Open Folder..., or simply drag the folder directly from our file browser into the VS Code window.

This practice helps the editor (and us!) understand how our files relate to one another. If we write a Python script that loads data from a data.csv file, the script will only run if the integrated terminal shares the same “current working directory” as the script. By opening the whole project folder in VS Code, the integrated terminal automatically opens in the correct location, our relative paths function properly, and the Explorer pane acts as a map of our entire project.

Getting started

Coming soon

Setup

Having configured Homebrew as in Chapter 3, installing VS Code is straightforward:

brew install --cask visual-studio-code

Since VS Code is installed as a graphical application (a cask), it appears in our Applications folder. We can launch the software using Spotlight (use , type “Visual Studio Code”, and hit ). We can also invoke the software from the terminal: after navigating to our project folder, the command code . launches an instance of VS Code with the current directory opened.

WarningDo You Trust the Authors?

When we first open a folder in VS Code, we will likely be greeted by a warning prompt asking: “Do you trust the authors of the files in this folder?”

We should pause to understand why VS Code is asking this. Modern code editors are very smart; when we open a folder, the editor immediately begins scanning the files to provide autocomplete suggestions, check for errors (linting), and configure environments. If we download a folder containing malicious code from the internet and open it in our editor, simply scanning those files can inadvertently execute hidden scripts. By asking for “Workspace Trust,” VS Code gives us a chance to open downloaded folders in “Restricted Mode,” allowing us to safely read the text without accidentally running anything. When we are creating our own folders for homework or research, we can confidently click “Yes, I trust the authors.”

After some initial configuration, we can find the Activity Bar on the far left side of the screen. This is our main navigation hub. For now, we emphasize two important tabs:

  1. The Explorer (the overlapping papers icon): Where the contents of the working directory are displayed.
  2. Extensions (the four blocks icon): Where we install plugins that enhance VS Code’s capabilities.

The Command Palette

An important feature of VS Code is the Command Palette, accessed via . This is comparable to macOS’s Spotlight, opening a search bar at the top of the screen which allows us to execute commands without having to dig through menus or memorize other hotkeys.

When the Command Palette opens, it is pre-filled with a > character, which tells the editor we are looking for a command. We can access the settings, change global theming, or restart the window simply by typing “settings”, “theme”, or “reload”.

Tip

If we open the Command Palette and delete the > character (or use the related shortcut ), the search bar instantly transforms into a file search! In a growing project with dozens of files, this is the fastest way to jump directly to a specific document without clicking through the Explorer tree.

Essential Extensions

By default, VS Code doesn’t actually know much about Python, \(\LaTeX\), or the other specialized tools we might use. Instead, it relies on the community to build extensions that teach the editor how to interact with different languages.

While we will cover specific extensions in their respective chapters, installing them always follows the same process:

  • Click the Extensions icon in the Activity Bar.
  • Search for the tool or language (e.g., “Python” or “Quarto”).
  • Locate the desired extension and click “Install”.
WarningTrusting Extensions

Extensions are developed by the community, not Microsoft. While many are safe and well-maintained, some may contain bugs, outdated features, or even malicious code. In general, we should:

  • Prefer official or highly-rated extensions.
  • Avoid obscure extensions with low ratings, few downloads, or unclear descriptions.
  • Always read the extension’s documentation page! Extensions often require specific software to be installed on our machine to function properly.

Integrated Terminal

Rather than having a separate terminal window open while we work, VS Code has one built-in. We can open it by pressing (the second character here is the backtick, usually located next to the 1 key on the numeric row) or by navigating to Terminal > New Terminal in the top menu.

This terminal works exactly like the standard macOS terminal we used to install Homebrew, but it automatically starts in the folder we currently have open in the Explorer. This means that we can easily run Python scripts, execute Git commands, or manage files without ever leaving our editor.

Note

When we are done using the terminal, clicking the X icon in the corner of the terminal pane only hides it—the terminal shell continues running in the background, consuming memory! To properly close the terminal, click the Trash Can icon, or type exit and press .

Settings

We can access the standard settings menu by pressing or via the Command Palette. This opens a graphical interface with hundreds of checkboxes and dropdowns for adjusting font sizes, autosave behaviors, and color themes. While this is straightforward, graphical menus can become overwhelming to navigate or cumbersome when attempting to replicate setups between different machines. Underneath the graphical interface, VS Code stores all of our preferences in a simple plaintext file called settings.json, which we can edit directly. To do so, we:

  1. Open the Command Palette ().
  2. Type “Settings”.
  3. Select Preferences: Open User Settings (JSON).

This file is a list of key-value pairs. When we configure VS Code—from simple settings to configuring advanced tools—we will directly edit this settings.json file. Because it is just text, we can easily back up or distribute this file! For now, let’s choose a nice theme that mirrors our system as it switches between Light and Dark mode:

settings.json
{
    "window.autoDetectColorScheme": true,
    "workbench.preferredDarkColorTheme": "Default Dark Modern",
    "workbench.preferredLightColorTheme": "Default Light Modern"
}

Best practices

Coming soon

Versioning

Coming Soon: VS Code provides native integration with git. We will explore how to visually track changes, stage commits, and manage branching in the Source Control tab in Chapter 4.