Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 243fa1f

Browse files
Adding developer guide
1 parent 8fd7a8f commit 243fa1f

File tree

1 file changed

+293
-0
lines changed

1 file changed

+293
-0
lines changed

‎DEVELOPER_LINTING_GUIDE.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
# Developer Linting and Code Formatting Guide
2+
3+
This guide helps contributors set up and use linting tools to maintain code quality standards in the mssql-python project.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Prerequisites](#prerequisites)
9+
- [Installation Instructions](#installation-instructions)
10+
- [Windows](#windows)
11+
- [macOS](#macos)
12+
- [Linux](#linux)
13+
- [Python Code Formatting](#python-code-formatting)
14+
- [C++ Code Formatting](#c-code-formatting)
15+
- [Pre-commit Hooks](#pre-commit-hooks)
16+
17+
## Overview
18+
19+
The mssql-python project uses multiple linting and formatting tools to ensure code quality:
20+
21+
- **Python**: `pylint` for linting (configured in `pyproject.toml`)
22+
- **C++**: `clang-format` for formatting, `cpplint` for linting (configured in `cpplint.cfg`)
23+
- **Pre-commit hooks**: Already configured in `.pre-commit-config.yml`
24+
25+
## Prerequisites
26+
27+
Before setting up linting tools, ensure you have:
28+
29+
- Python 3.8+ installed
30+
- Git installed and configured
31+
- A working development environment for the project
32+
33+
## Quick Start (TL;DR)
34+
35+
**For new contributors, this is all you need:**
36+
37+
1. **Install dependencies:**
38+
```bash
39+
pip install -r requirements.txt
40+
```
41+
42+
2. **Set up pre-commit hooks:**
43+
```bash
44+
pre-commit install
45+
```
46+
47+
3. **Install clang-format** (see OS-specific instructions below)
48+
49+
4. **Verify setup:**
50+
```bash
51+
pre-commit run --all-files
52+
```
53+
54+
Now your code will be automatically checked before each commit!
55+
56+
## Installation Instructions
57+
58+
### Windows
59+
60+
#### Using PowerShell (Administrator recommended for some installations)
61+
62+
1. **Install Python linting tools:**
63+
```powershell
64+
pip install -r requirements.txt
65+
```
66+
67+
2. **Install clang-format:**
68+
69+
**Option A: Using Chocolatey (Recommended)**
70+
```powershell
71+
# Install Chocolatey first if not installed
72+
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
73+
74+
# Install LLVM (includes clang-format)
75+
choco install llvm
76+
```
77+
78+
**Option B: Using winget**
79+
```powershell
80+
winget install LLVM.LLVM
81+
```
82+
83+
84+
3. **Verify installations:**
85+
```powershell
86+
python --version
87+
pylint --version
88+
clang-format --version
89+
cpplint --help
90+
```
91+
92+
### macOS
93+
94+
1. **Install Python linting tools:**
95+
```bash
96+
pip install -r requirements.txt
97+
```
98+
99+
2. **Install clang-format:**
100+
```bash
101+
# Using Homebrew (recommended)
102+
brew install clang-format
103+
104+
# Alternative: Install full LLVM suite
105+
brew install llvm
106+
```
107+
108+
3. **Verify installations:**
109+
```bash
110+
python --version
111+
pylint --version
112+
clang-format --version
113+
cpplint --help
114+
```
115+
116+
### Linux
117+
118+
#### Ubuntu/Debian
119+
120+
1. **Install system dependencies:**
121+
```bash
122+
sudo apt update
123+
sudo apt install clang-format python3-pip
124+
```
125+
126+
2. **Install Python linting tools:**
127+
```bash
128+
pip install -r requirements.txt
129+
```
130+
131+
#### Red Hat/CentOS/Fedora
132+
133+
1. **Install system dependencies:**
134+
```bash
135+
# For RHEL/CentOS 8+
136+
sudo dnf install clang-tools-extra python3-pip
137+
138+
# For older versions
139+
sudo yum install clang python3-pip
140+
```
141+
142+
2. **Install Python linting tools:**
143+
```bash
144+
pip install -r requirements.txt
145+
```
146+
147+
## Python Code Formatting
148+
149+
### Using Pylint
150+
151+
The project uses pylint for Python code quality checks with custom configuration in `pyproject.toml`.
152+
153+
**Check a single file:**
154+
```bash
155+
pylint mssql_python/connection.py
156+
```
157+
158+
**Check all Python files:**
159+
```bash
160+
# Windows PowerShell
161+
Get-ChildItem -Recurse -Path mssql_python -Include *.py | ForEach-Object { pylint $_.FullName }
162+
163+
# macOS/Linux
164+
find mssql_python -name "*.py" -exec pylint {} \;
165+
```
166+
167+
**Check specific directories:**
168+
```bash
169+
pylint mssql_python/ tests/
170+
```
171+
172+
### Project Configuration
173+
174+
The project uses Pylint configuration defined in `pyproject.toml`:
175+
- Line length: 100 characters
176+
- Minimum score: 8.5
177+
- Disabled checks: fixme, no-member, too-many-arguments, etc.
178+
179+
**Current project standards:** The project currently uses Pylint for both linting and enforcing formatting standards. While Black could be added for automatic formatting, the current setup relies on Pylint's formatting rules.
180+
181+
## C++ Code Formatting
182+
183+
### Using clang-format
184+
185+
The project has a `.clang-format` configuration file with Google style guidelines.
186+
187+
**Format a single file:**
188+
```bash
189+
clang-format -i mssql_python/pybind/ddbc_bindings.cpp
190+
```
191+
192+
**Format all C++ files:**
193+
```bash
194+
# Windows PowerShell
195+
Get-ChildItem -Recurse -Path mssql_python/pybind -Include *.cpp,*.h,*.hpp | ForEach-Object { clang-format -i $_.FullName }
196+
197+
# macOS/Linux
198+
find mssql_python/pybind -name "*.cpp" -o -name "*.h" -o -name "*.hpp" | xargs clang-format -i
199+
```
200+
201+
**Check formatting without modifying files:**
202+
```bash
203+
clang-format --dry-run --Werror mssql_python/pybind/ddbc_bindings.cpp
204+
```
205+
206+
### Using cpplint
207+
208+
The project has a `cpplint.cfg` configuration file with:
209+
- Line length: 100 characters
210+
- Filtered out: readability/todo warnings
211+
- Excludes: build directory
212+
213+
**Check C++ code style:**
214+
```bash
215+
# Single file (uses project config automatically)
216+
cpplint mssql_python/pybind/ddbc_bindings.cpp
217+
218+
# All C++ files
219+
# Windows PowerShell
220+
Get-ChildItem -Recurse -Path mssql_python/pybind -Include *.cpp,*.h,*.hpp | ForEach-Object { cpplint $_.FullName }
221+
222+
# macOS/Linux
223+
find mssql_python/pybind -name "*.cpp" -o -name "*.h" -o -name "*.hpp" | xargs cpplint
224+
```
225+
226+
## Pre-commit Hooks
227+
228+
**Good news!** The project already has pre-commit hooks configured in `.pre-commit-config.yml`.
229+
230+
The current configuration includes:
231+
- **Pylint**: Using `pre-commit/mirrors-pylint` (v3.0.0a5)
232+
- **cpplint**: Local hook with project-specific arguments:
233+
- Filters out readability/todo warnings
234+
- Line length: 100 characters
235+
- Excludes build directory
236+
237+
### Setting up pre-commit hooks:
238+
239+
1. **Install pre-commit (already in requirements.txt):**
240+
```bash
241+
pip install pre-commit
242+
```
243+
244+
2. **Install the hooks:**
245+
```bash
246+
pre-commit install
247+
```
248+
249+
3. **Run hooks on all files (optional):**
250+
```bash
251+
pre-commit run --all-files
252+
```
253+
254+
4. **Run specific hooks:**
255+
```bash
256+
# Run only pylint
257+
pre-commit run pylint
258+
259+
# Run only cpplint
260+
pre-commit run cpplint
261+
```
262+
263+
### How it works:
264+
- Hooks run automatically on `git commit`
265+
- Only files being committed are checked
266+
- Commit is blocked if linting fails
267+
- You can bypass with `git commit --no-verify` (not recommended)
268+
269+
## Best Practices
270+
271+
1. **Always run linting before committing:**
272+
- Set up pre-commit hooks
273+
- Run manual checks for critical changes
274+
275+
2. **Fix linting issues promptly:**
276+
- Don't accumulate technical debt
277+
- Address issues in the same PR that introduces them
278+
279+
3. **Understand the rules:**
280+
- Read pylint and cpplint documentation
281+
- Understand why certain patterns are discouraged
282+
283+
4. **Team consistency:**
284+
- Follow the project's existing style
285+
- Discuss style changes in team meetings
286+
287+
## Additional Resources
288+
289+
- [Pylint Documentation](https://pylint.pycqa.org/en/latest/)
290+
- [Black Documentation](https://black.readthedocs.io/en/stable/)
291+
- [Clang-Format Documentation](https://clang.llvm.org/docs/ClangFormat.html)
292+
- [cpplint Style Guide](https://google.github.io/styleguide/cppguide.html)
293+
- [Pre-commit Documentation](https://pre-commit.com/)

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /