This mssql-python module helps developers set up their development environment for the mssql-python project with automatic code formatting and linting.

• Prerequisites
• VS Code Extensions
• Automatic Formatting
• Linting Configuration
• Verification
• Troubleshooting

1. Visual Studio Code (latest version)
2. Python 3.8+ (Python 3.13+ recommended)
3. clang-format (version 10+)
4. Git (for version control)

# Check Python version
python3 --version

# Check clang-format
clang-format --version

# Check pip
python3 -m pip --version

Install the following extensions in VS Code (Ctrl+Shift+X):

1. Python (ms-python.python)

   • Core Python language support
   • IntelliSense, debugging, linting

2. Black Formatter (ms-python.black-formatter)

   • Python code formatter (Microsoft's recommended)
   • Enforces consistent code style

3. autopep8 (ms-python.autopep8)

   • Alternative Python formatter (backup)

4. Pylint (ms-python.pylint)

   • Python linter for code quality

5. Flake8 (ms-python.flake8)

   • Python style guide enforcement

1. C/C++ (ms-vscode.cpptools)

   • Microsoft's official C++ extension
   • IntelliSense, debugging, formatting with clang-format

2. C/C++ Extension Pack (ms-vscode.cpptools-extension-pack)

   • Bundle of useful C++ tools

3. Clang-Format (xaver.clang-format)

   • Advanced clang-format integration

4. C/C++ Linter (cpplint) (mine.cpplint)

   • Google C++ style guide checker

# Run in VS Code terminal or PowerShell
code --install-extension ms-python.python
code --install-extension ms-python.black-formatter
code --install-extension ms-python.autopep8
code --install-extension ms-python.pylint
code --install-extension ms-python.flake8
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cpptools-extension-pack
code --install-extension xaver.clang-format
code --install-extension mine.cpplint

# Navigate to project root
cd mssql-python

# Install cpplint for C++ linting
python3 -m pip install cpplint

# Install Python development tools (if not already installed)
python3 -m pip install black flake8 pylint autopep8

✅ Python Files (.py)

• Formatter: Black (line length: 100)
• On Save: Automatically formats code
• Import Organization: Automatically sorts imports

✅ C++ Files (.cpp, .c, .h, .hpp)

• Formatter: clang-format (uses .clang-format config)
• On Save: Automatically formats code
• Style Guide: Microsoft/LLVM style with modifications
• Comment Spacing: Ensures minimum 2 spaces before inline comments (cpplint compliant)

The project includes pre-configured settings:

1. .vscode/settings.json - VS Code workspace settings (see detailed changes below)
2. .clang-format - C++ formatting rules
3. pyproject.toml - Python tool configuration
4. .flake8 - Python style guide settings

The following settings were configured in the workspace settings file:

Global Formatting Settings:

{
  "editor.formatOnSave": true,
  "editor.formatOnType": false,
  "files.trimTrailingWhitespace": true
}

Python-Specific Settings:

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },
  "black-formatter.args": ["--line-length=100"],
  "autopep8.args": ["--max-line-length=100"],
  "flake8.args": ["--max-line-length=100", "--extend-ignore=E203,W503"],
  "pylint.args": [
    "--max-line-length=100",
    "--disable=fixme,no-member,too-many-arguments,too-many-positional-arguments,invalid-name,useless-parent-delegation"
  ]
}

Python Type Checking (Pylance):

{
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.autoImportCompletions": true,
  "python.analysis.inlayHints.functionReturnTypes": true,
  "python.analysis.inlayHints.variableTypes": true,
  "python.analysis.inlayHints.pytestParameters": true,
  "python.analysis.diagnosticSeverityOverrides": {
    "reportMissingTypeStubs": "none",
    "reportUnknownMemberType": "none",
    "reportUnknownArgumentType": "none"
  }
}

C++ Formatting Settings:

{
  "[cpp]": {
    "editor.defaultFormatter": "xaver.clang-format",
    "editor.formatOnSave": true
  },
  "[c]": {
    "editor.defaultFormatter": "ms-vscode.cpptools",
    "editor.formatOnSave": true
  },
  "[h]": {
    "editor.defaultFormatter": "ms-vscode.cpptools",
    "editor.formatOnSave": true
  },
  "[hpp]": {
    "editor.defaultFormatter": "ms-vscode.cpptools",
    "editor.formatOnSave": true
  },
  "C_Cpp.clang_format_path": "clang-format",
  "C_Cpp.clang_format_style": "file",
  "C_Cpp.clang_format_fallbackStyle": "LLVM"
}

cpplint Settings:

{
  "cpplint.cpplintPath": "python3 -m cpplint",
  "cpplint.lintMode": "workspace",
  "cpplint.filters": [
    "-legal/copyright",
    "-build/include_subdir",
    "-build/c++11"
  ],
  "cpplint.lineLength": 100
}

Key Changes Made:

1. ✅ Enabled formatOnSave globally and per-language
2. ✅ Set Black as default Python formatter with 100-char line length
3. ✅ Configured all Python linters (Pylint, Flake8, autopep8) to use 100-char lines
4. ✅ Enabled Pylance type checking with "basic" mode and inlay hints
5. ✅ Configured clang-format for C++ files with explicit formatter per file type
6. ✅ Set cpplint to use python3 -m cpplint command with custom filters
7. ✅ Disabled specific Python diagnostic warnings to reduce noise
8. ✅ Enabled automatic import organization on save for Python files

Enabled Linters:

• Pylint: Code quality and error detection
• Flake8: Style guide enforcement (PEP 8)

Configuration:

• Line length: 100 characters (not 79)
• Ignores: E203, W503 (conflicts with Black)
• Custom rules in pyproject.toml and .flake8

Disabled Warnings:

# Disabled in pylint
- fixme
- no-member
- too-many-arguments
- too-many-positional-arguments
- invalid-name
- useless-parent-delegation

Enabled Linter:

• cpplint: Google C++ Style Guide checker

Configuration:

• Line length: 100 characters
• Filtered warnings:
  • -legal/copyright (no copyright headers required)
  • -build/include_subdir (allow flexible includes)
  • -build/c++11 (modern C++ features allowed)

Run manually:

# Check a specific file
python3 -m cpplint --filter=-legal/copyright,-build/include_subdir,-build/c++11 --linelength=100 mssql_python\pybind\ddbc_bindings.cpp

# Check all C++ files
python3 -m cpplint --filter=-legal/copyright,-build/include_subdir,-build/c++11 --linelength=100 --recursive mssql_python\pybind

The project uses Pylance with type checking enabled:

• Type Checking Mode: basic
• Inlay Hints: Enabled for function returns, variables, and parameters
• Auto-imports: Enabled for better productivity

View Type Information:

• Hover over any variable/function to see type hints
• Press Ctrl+Space for IntelliSense with type information

1. Open any Python file (e.g., mssql_python/connection.py)
2. Make a small change (add extra spaces)
3. Press Ctrl+S to save
4. ✅ File should auto-format with proper spacing

Manual format: Press Shift+Alt+F

1. Open any C++ file (e.g., mssql_python/pybind/ddbc_bindings.cpp)
2. Make a small change (add extra spaces or misalign code)
3. Press Ctrl+S to save
4. ✅ File should auto-format with proper indentation and spacing

Manual format: Press Shift+Alt+F

Before formatting:

int value = 42; // This comment has only 1 space

After formatting (auto-fixed on save):

int value = 42;  // This comment has 2 spaces (cpplint compliant)

1. Open the Problems panel: Ctrl+Shift+M
2. You'll see linting errors/warnings from:
   • Pylint (Python)
   • Flake8 (Python)
   • cpplint (C++)

Issue: Black formatter doesn't run on save

Solution:

1. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"
2. Check if Black is installed: python3 -m black --version
3. Verify settings: Open .vscode/settings.json and check:

   "[python]": {
     "editor.defaultFormatter": "ms-python.black-formatter"
   }

Issue: clang-format doesn't run on save

Solutions:

1. Check clang-format installation:

   clang-format --version

2. Disable conflicting formatters:

   • Open Extensions (Ctrl+Shift+X)
   • Search for "Clang-Format"
   • If you see multiple formatters, disable the third-party ones
   • Keep only ms-vscode.cpptools enabled

3. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"

4. Test manual formatting: Shift+Alt+F in a C++ file

Issue: cpplint command not recognized

Solution:

# Install cpplint
python3 -m pip install cpplint

# Verify installation
python3 -m cpplint --version

Issue: Changes to .vscode/settings.json not taking effect

Solutions:

1. Close and reopen VS Code
2. Check for syntax errors in settings.json (no trailing commas)
3. Check VS Code Output: View → Output → Select "Extension Host"

Issue: Different tools report different line length limits

Our Standards:

• Python: 100 characters (Black, Flake8, Pylint)
• C++: 100 characters (clang-format, cpplint)

All tools are configured for 100-character lines to maintain consistency.

1. Save all files - This triggers auto-formatting
2. Check Problems panel (Ctrl+Shift+M) - Fix any linting errors
3. Run tests - Ensure formatting didn't break anything
4. Review changes - Use git diff to see formatting changes

If auto-format doesn't work:

Format current file:

Shift+Alt+F

Format selection:

Ctrl+K Ctrl+F

Format on type (disabled by default):

"editor.formatOnType": true

To change line length (not recommended):

Python - Edit pyproject.toml:

[tool.black]
line-length = 100  # Change this value

C++ - Edit .clang-format:

ColumnLimit: 100  # Change this value

If you need to disable auto-formatting temporarily:

1. Open Command Palette: Ctrl+Shift+P
2. Run: "Preferences: Open Settings (JSON)"
3. Add:

   "editor.formatOnSave": false

• VS Code Docs: https://code.visualstudio.com/docs
• Black Formatter: https://black.readthedocs.io/
• clang-format: https://clang.llvm.org/docs/ClangFormat.html
• cpplint: https://github.com/cpplint/cpplint
• PEP 8: https://pep8.org/

• Check existing issues in the project repository
• Ask team lead or senior developers
• Review code review feedback for formatting standards

The project includes a GitHub Actions workflow (.github/workflows/lint-check.yml) that automatically checks all PRs for linting issues.

What Gets Checked:

✅ Python Linting (on every PR):

• Black formatting - Ensures code follows Black style (100-char lines)
• Flake8 - Checks PEP 8 compliance and style issues
• Pylint - Analyzes code quality and potential bugs
• mypy (optional) - Verifies type hints are correct

✅ C++ Linting (on every PR):

• clang-format - Verifies code formatting matches .clang-format rules
• cpplint - Checks Google C++ Style Guide compliance (with custom filters)

1. On PR Creation/Update:

   • Workflow runs automatically on all PRs to main or develop branches
   • Only runs if Python or C++ files are changed

2. Linting Checks:

   • Python files are checked with Black, Flake8, and Pylint
   • C++ files are checked with clang-format and cpplint
   • Errors are highlighted directly in the PR

3. PR Status:

   • ✅ Green check - All linting passed, PR can be merged
   • ❌ Red X - Linting issues found, must be fixed before merge
   • ⚠️ Yellow warning - Minor issues, review recommended

4. View Results:

   • Click "Details" next to the check in the PR
   • Review specific errors in the "Files changed" tab
   • Check the Actions tab for full logs

Before Pushing to PR:

# Format Python files
black --line-length=100 mssql_python/ tests/

# Check Python linting
flake8 mssql_python/ tests/ --max-line-length=100 --extend-ignore=E203,W503

# Format C++ files
clang-format -i mssql_python/pybind/*.cpp mssql_python/pybind/*.h

# Check C++ linting
python3 -m cpplint --filter=-legal/copyright,-build/include_subdir,-build/c++11 --linelength=100 --recursive mssql_python/pybind

Or Simply:

• Save all files in VS Code (Ctrl+S) - auto-formatting will fix most issues!
• Check the Problems panel (Ctrl+Shift+M) for remaining issues
• Fix any remaining linting errors manually

The linting workflow runs on:

• Pull Requests to main or develop branches
• Direct pushes to main or develop (if allowed)
• Changes to Python files (**.py)
• Changes to C++ files (**.cpp, **.c, **.h, **.hpp)
• Changes to config files (.flake8, pyproject.toml, .clang-format)

In rare cases, you may need to bypass linting:

1. Add inline comments:

   # pylint: disable=line-too-long
   very_long_line = "This is an exceptionally long line that cannot be broken..."

   // NOLINTNEXTLINE(whitespace/line_length)
   std::string long_string = "This is a very long C++ string...";

2. Mark as draft PR:

   • Draft PRs don't require passing checks
   • Convert to "Ready for review" when linting is fixed

View Workflow Status:

1. Go to repository → Actions tab
2. Select "Linting Check" workflow
3. View recent runs and success rate

Best Practice:

• Keep linting errors low (< 50 for C++, 0 for Python)
• Fix issues immediately when raised
• Don't accumulate technical debt

✅ Auto-formatting is configured for:

• Python files (.py) - Black formatter, 100 char lines
• C++ files (.cpp, .c, .h, .hpp) - clang-format, 100 char lines

✅ Linting is enabled for:

• Python - Pylint + Flake8
• C++ - cpplint (Google Style Guide)

✅ Type checking is enabled:

• Python - Pylance with basic mode

✅ CI/CD checks:

• Automated linting on every PR
• Blocks merge if critical issues found
• Summary report in PR status

Just save your files (Ctrl+S) and formatting happens automatically! 🎉