diff --git a/docs/tech_docs/python/python_rules.md b/docs/tech_docs/python/python_rules.md new file mode 100644 index 0000000..f5951af --- /dev/null +++ b/docs/tech_docs/python/python_rules.md @@ -0,0 +1,72 @@ +# Python Style Guide + +## Table of Contents + +1. [Code Layout](#code-layout) +2. [Naming Conventions](#naming-conventions) +3. [Comments](#comments) +4. [Docstrings](#docstrings) +5. [Imports](#imports) +6. [Whitespace in Expressions and Statements](#whitespace-in-expressions-and-statements) +7. [Programming Recommendations](#programming-recommendations) +8. [Testing](#testing) + +## Code Layout + +- **Indentation**: Use 4 spaces per indentation level. +- **Line Length**: Limit all lines to a maximum of 79 characters. +- **Blank Lines**: Use blank lines to separate functions and classes, and larger blocks of code inside functions. +- **Encoding**: Use UTF-8 encoding for Python 3. + +## Naming Conventions + +- **Modules**: Short, lowercase names, preferably without underscores. +- **Classes**: Use the CapWords convention. +- **Functions**: Lowercase, with words separated by underscores. +- **Variables**: Lowercase, with words separated by underscores. +- **Constants**: Uppercase, with words separated by underscores. + +## Comments + +- **Inline Comments**: Use sparingly and focus on why, not what. +- **Block Comments**: Indent to the same level as the code it describes. + +## Docstrings + +- **Public Modules**: Describe what the module contains and its purpose. +- **Functions**: Describe what the function does and its arguments. +- **Classes**: Describe what the class does. + +## Imports + +- **Import Order**: Within each import group (standard library, third-party, local), sort the imports alphabetically. +- **Standard Library Imports**: First, separate from third-party libraries. +- **Related Third-Party Imports**: Second. +- **Local Application/Library Specific Imports**: Third. +- **Absolute Imports**: Prefer absolute imports over relative imports to improve readability and avoid issues with module naming conflicts. +- **Wildcards**: Avoid using wildcard imports (`from module import *`) as they can pollute the namespace and make it unclear which names are present. + +## Whitespace in Expressions and Statements + +- Avoid extraneous whitespace in the following situations: + - Immediately inside parentheses, brackets, or braces. + - Between a trailing comma and a following close parenthesis. + - Immediately before a comma, semicolon, or colon. +- **Binary Operators**: Surround binary operators with a single space on either side for readability, except when assigning default parameter values in function definitions. +- **Compound Statements**: Avoid using backslash line continuation. Instead, use implicit line joining within parentheses, brackets, and braces. + +## Programming Recommendations + +- **`is not` over `not ... is`**: Use `is not` operator rather than `not ... is`. +- **List Comprehensions**: Preferable over multiple `for` and `if` statements. +- **String Quotes**: Prefer single quotes for string literals, unless the string contains a single quote character. Use double quotes for triple-quoted strings and docstrings. +- **Exception Handling**: Use specific exception classes when catching exceptions, rather than using a bare `except:` clause. Avoid catching `Exception` or `StandardError` unless you are re-raising the exception or in the outermost block in a thread. +- **Context Managers**: Use context managers (`with` statement) when working with file objects and other resources that need to be properly closed or released. +- **Generator Expressions**: Consider using generator expressions instead of list comprehensions for large datasets or when you don't need to store the entire result in memory. + +## Testing + +- **Test Framework**: Use a standard testing framework like `unittest` or `pytest` to write and run tests for your code. +- **Test Coverage**: Strive for high test coverage to ensure your code is well-tested and to catch potential bugs early in the development process. + +Remember, this is a starting guide. Feel free to adapt and expand it based on the needs of your projects and your personal preferences. \ No newline at end of file