Editor Setup Guide

This guide covers setting up VS Code (recommended) and PyCharm for our development stack.

VS Code Setup (Recommended) link

Installation link

Download from code.visualstudio.com

Required Extensions link

Install these extensions (Cmd+Shift+X or Ctrl+Shift+X):

Python:

1. Python (Microsoft) - ms-python.python
2. Pylance (Microsoft) - ms-python.vscode-pylance
3. Ruff (Charliermarsh) - charliermarsh.ruff

JavaScript/TypeScript: 4. Bun (Oven) - oven.bun-vscode 5. Biome (Biomejs) - biomejs.biome (replaces ESLint + Prettier)

General: 7. GitLens (GitKraken) - eamodio.gitlens 8. Docker (Microsoft) - ms-azuretools.vscode-docker 9. EditorConfig (EditorConfig) - editorconfig.editorconfig

Database: 10. SQLTools (Matheus Teixeira) - mtxr.sqltools 11. SQLTools PostgreSQL (Matheus Teixeira) - mtxr.sqltools-driver-pg

Optional but Useful:

• TODO Highlight - wayou.vscode-todo-highlight
• Error Lens - usernamehw.errorlens
• Auto Rename Tag - formulahendry.auto-rename-tag
• Path Intellisense - christian-kohler.path-intellisense

Settings Configuration link

Create .vscode/settings.json in your project:

  {
  // Editor
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": "always"
  },
  "editor.rulers": [88, 100],
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,

  // Python
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "always"
    }
  },
  "python.analysis.typeCheckingMode": "basic",

  // JavaScript/TypeScript
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },

  // JSON/YAML
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[yaml]": {
    "editor.defaultFormatter": "biomejs.biome"
  },

  // Git
  "git.autofetch": true,
  "git.confirmSync": false,

  // Files
  "files.exclude": {
    "**/__pycache__": true,
    "**/*.pyc": true,
    "**/.pytest_cache": true,
    "**/.mypy_cache": true,
    "**/node_modules": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/.venv": true,
    "**/venv": true
  }
}
  

Debugging Configuration link

Create .vscode/launch.json:

  {
  "version": "0.2.0",
  "configurations": [
    {
      "name": "FastAPI",
      "type": "python",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "app.main:app",
        "--reload",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "jinja": true,
      "justMyCode": false,
      "env": {
        "ENVIRONMENT": "local"
      }
    },
    {
      "name": "Pytest: Current File",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": ["${file}", "-v"],
      "console": "integratedTerminal",
      "justMyCode": false
    },
    {
      "name": "Pytest: All Tests",
      "type": "python",
      "request": "launch",
      "module": "pytest",
      "args": ["-v"],
      "console": "integratedTerminal",
      "justMyCode": false
    }
  ]
}
  

Keyboard Shortcuts link

Useful shortcuts (macOS / Windows):

Database Connection link

Using SQLTools:

1. Click SQLTools icon in sidebar
2. Click “Add New Connection”
3. Select PostgreSQL
4. Enter details:

     Connection name: Local Dev
   Server: localhost
   Port: 5432
   Database: yourapp_dev
   Username: postgres
   Password: postgres
     

5. Test connection → Save

PyCharm Setup (Alternative) link

Installation link

Download PyCharm Professional from jetbrains.com/pycharm

Configuration link

1. Set Python Interpreter:

• Settings → Project → Python Interpreter
• Add → Virtualenv Environment → Existing environment
• Select venv/bin/python

2. Enable EditorConfig:

• Settings → Editor → Code Style
• ✅ Enable EditorConfig support

3. Configure Black:

• Settings → Tools → Black
• ✅ On save
• ✅ On code reformat
• Arguments: --line-length 88

4. Configure isort:

• Settings → Tools → Actions on Save
• ✅ Run isort
• Configuration: --profile black

5. Configure flake8:

• Settings → Tools → External Tools → Add
• Name: flake8
• Program: $ProjectFileDir$/venv/bin/flake8
• Arguments: $FilePath$

6. Database Tools:

• View → Tool Windows → Database
• • → PostgreSQL
• Enter connection details
• Test connection → OK

Linter Configuration link

.editorconfig link

Copy from templates:

  cp docs/04-templates/.editorconfig .editorconfig
  

This configures basic editor behaviour (spaces vs tabs, line endings, etc.)

Python: .flake8 (DEPRECATED) link

Note: .flake8 is no longer used - Ruff replaces flake8. All configuration is in pyproject.toml under [tool.ruff].

Python: pyproject.toml link

  [tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP"]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

[tool.ty]
# ty uses smart defaults
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
  

JavaScript/TypeScript: biome.json link

Biome replaces both ESLint and Prettier:

  {
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  }
}
  

Format on Save link

VS Code link

Already configured in settings.json:

  "editor.formatOnSave": true
  

PyCharm link

Settings → Tools → Actions on Save:

• ✅ Reformat code
• ✅ Optimize imports
• ✅ Run isort

Verification link

Test that everything works:

1. Create test file:

  # test_format.py
import  sys
from    typing import List


def  hello(name:str)->str:
    return f"Hello {name}"


x=hello("World")
print(x)
  

2. Save file:

• File should auto-format on save
• Imports should be sorted
• Spacing should be corrected

3. Expected result:

  # test_format.py
import sys
from typing import List


def hello(name: str) -> str:
    return f"Hello {name}"


x = hello("World")
print(x)
  

Troubleshooting link

Format on Save Not Working link

VS Code:

1. Check Settings → search “format on save”
2. Ensure it’s enabled
3. Check formatter is selected for language
4. Reload window: Cmd+Shift+P → “Reload Window”

PyCharm:

1. Settings → Tools → Actions on Save
2. Ensure “Reformat code” is checked
3. Check Python interpreter is set correctly

Linter Not Running link

VS Code:

1. Check extension is installed and enabled
2. Check virtual environment is activated
3. Reload window

PyCharm:

1. Settings → Editor → Inspections
2. Ensure Python inspections are enabled
3. Check interpreter is correct

EditorConfig Not Working link

1. Ensure EditorConfig extension installed (VS Code)
2. Ensure .editorconfig is in project root
3. Reload editor

Best Practices link

✅ Do:

• Use same editor settings as team
• Configure format on save
• Keep extensions updated
• Use linter recommendations
• Configure debugger

❌ Don’t:

• Ignore linter warnings
• Skip EditorConfig
• Have different settings per project
• Commit editor-specific files (.idea/, .vscode/)

Next Steps link

• Set up pre-commit hooks: pre-commit-hooks.md
• Review code standards: ../02-standards/code-standards.md
• Configure API testing: api-testing.md