Johan Dahlin
50366b9b9c
All checks were successful
Deploy Quartz site to GitHub Pages / build (push) Successful in 2m29s
57 lines
3.0 KiB
Markdown
57 lines
3.0 KiB
Markdown
# Markdown
|
||
Use Obsidian-flavored Markdown.
|
||
Use fenced code blocks for code snippets, indicating the language when appropriate.
|
||
Avoid extra new lines, prefer fewer new lines and compact formatting.
|
||
|
||
# Coding
|
||
The rest of this document describes coding conventions to follow when writing code.
|
||
|
||
## General
|
||
- Do not create comments nor docstrings when updating code unless asked.
|
||
- Do not create a summary .md file unless asked.
|
||
- Do not create a README.md file unless asked.
|
||
- When installing a new dependency, prefer to use the latest version.
|
||
- Try to reduce indentation, prefer to use early returns or continue everwhere, be excessive about it.
|
||
|
||
## Python
|
||
- Use uv for handling python installations
|
||
- Use pyproject.toml to handle dependencies
|
||
- Avoid exceptions if possible
|
||
- When exceptions are necessary, use specific exception types, provide meaningful messages, and handle them appropriately.
|
||
- Exceptions try/except blocks should be as narrow as possible, try extra hard to avoid catching exceptions you did not intend to catch.
|
||
- Use type hints for all functions and methods.
|
||
- Use global constants for compiled regex patterns, capitalized and ending with `_RE`.
|
||
- Document regex patterns with inline comments using multiple strings inside `re.compile()`. This overrides the general rule against docstrings/comments.
|
||
|
||
## Python unit testing:
|
||
- we should have a tests package under each implementation that has a test and the corresponding test foo/bar.py is tested in foo/bar/tests/test_bar.py
|
||
- Use pytest framework, version 9 or higher.
|
||
- Configure using pyproject.toml, avoid pytest.ini to be able to have all configuration in one place.
|
||
- Prefer parametrized tests for functions that need to be tested with multiple sets of inputs and expected outputs.
|
||
- Use the new `with pytest.test(...)´ for that purpose:
|
||
|
||
```python
|
||
import pytest
|
||
def test_parametrized(subtests: pytest.Subtests) -> None:
|
||
# ... setup code ...
|
||
parameters = [...]
|
||
for ... in parameters:
|
||
with subtests.test(x=...):
|
||
assert ...
|
||
# ... tear down ...
|
||
```
|
||
|
||
## Django
|
||
|
||
- Prefer function based views over class based views
|
||
- Use django-stubs for type hints
|
||
- Use pytest-django for testing django applications
|
||
- Avoid comments in settings.
|
||
|
||
## Style Learnings
|
||
- **Stateful Parsing**: For complex tasks like parsing, prefer stateful classes that share context via `self` to avoid passing many arguments.
|
||
- **Match Statement Inlining**: Prefer inlining simple, single-statement logic directly into `match` cases.
|
||
- **Semantic Naming**: Use names that reflect the domain (e.g. `answer`) rather than implementation details (e.g. `spoiler`).
|
||
- **Data Propagation**: Ensure all calculated metrics (like question counts) are consistently propagated to the final output structure.
|
||
- **Factory Helpers**: Use centralized factory methods (e.g. `_create_question`) to instantiate objects with many shared common fields.- **Test Organization**: Place tests in a `tests` package within each implementation directory. Test files should be named `test_xxx.py` corresponding to the `xxx.py` file they test.
|