[docs] Add style guide #58
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit introduces STYLE_GUIDE.md in the docs/ directory to outline coding conventions, patterns, and best practices for the project. Key changes from any previous (uncommitted) versions: - Moved the style guide to `docs/STYLE_GUIDE.md`. - Added a dedicated 'Testing' section with expanded guidelines on: - Test location and naming. - Use of Pytest fixtures (e.g., `LoggingEnvironment` pattern). - Test parametrization. - Writing clear, focused, and robust test cases. - Clarified Markdown heading usage versus internal code comment sectioning. The guide covers: - Use of automated formatters/linters (Black, Pylint, MyPy). - Import organization. - Naming conventions. - Type hinting requirements. - Docstring standards (Google style via mkdocstrings) with version markers. - Rule for explicit return statements. - Class structure and internal code commenting conventions. - Common code patterns (versioning, TypeAlias, custom exceptions, utils).
This commit implements several improvements to the project's style guide
and its integration into the contribution process:
1. **Style Guide Content and Structure (`docs/style-guide.md`):**
* Reordered sections for better logical flow.
* Added references to PEP 8 and PEP 20 (Zen of Python) under
'General Principles'.
* Refined rules to differentiate between general Python best
practices and project-specific conventions (e.g., import
grouping, `TypeAlias` usage, explicit returns, version markers
in docstrings, `LoggingEnvironment` test pattern).
* Removed some overly common Python rules to reduce verbosity.
* Clarified naming for 'Project-Specific Code Patterns and Idioms'
and added the conditional import pattern.
2. **File Renaming:**
* Renamed `docs/STYLE_GUIDE.md` to `docs/style-guide.md` to match
the naming convention of other documentation files.
3. **Contributing Guide Update (`docs/contributing.md`):**
* Added a new 'Coding Style' subsection under 'Fork the repository
and make your changes'.
* This new subsection explicitly directs contributors to read and
adhere to the `docs/style-guide.md`.
nhairs
commented
Jun 26, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The guide covers: