From 4e5f863bddc48714fff100df94c2685b00a0b822 Mon Sep 17 00:00:00 2001 From: ll7 <32880741+ll7@users.noreply.github.com> Date: Thu, 24 Oct 2024 15:40:22 +0200 Subject: [PATCH] Update documentation requirements and linting guidelines (#352) Fixes #286 and [Feature]: Discuss how to deal with templates #324 --- doc/development/documentation_requirements.md | 80 +++++++++++++------ doc/development/linting.md | 9 +-- 2 files changed, 57 insertions(+), 32 deletions(-) diff --git a/doc/development/documentation_requirements.md b/doc/development/documentation_requirements.md index e75fa783..1c3dc846 100644 --- a/doc/development/documentation_requirements.md +++ b/doc/development/documentation_requirements.md @@ -1,21 +1,49 @@ # Documentation Requirements -**Summary:** This document provides the guidelines for the documentation. - -- [Documentation Requirements](#documentation-requirements) - - [Python Docstrings](#python-docstrings) - - [Readability and Maintainability](#readability-and-maintainability) - - [Code Structure](#code-structure) - - [Efficiency and Performance](#efficiency-and-performance) - - [Error Handling](#error-handling) - - [Testing](#testing) - - [Security](#security) - - [Documentation](#documentation) - - [Version Control](#version-control) - - [Scalability](#scalability) - - [Consistency with Coding Standards](#consistency-with-coding-standards) - -## Python Docstrings +**Summary:** This document outlines the guidelines for documentation to ensure consistency, readability, maintainability, and adherence to best practices in coding standards. + +- [1. Linting](#1-linting) + - [1.1. Python Linting](#11-python-linting) + - [1.2. Markdown Linting](#12-markdown-linting) +- [2. Templates](#2-templates) +- [3. Python Docstrings](#3-python-docstrings) +- [4. Readability and Maintainability](#4-readability-and-maintainability) +- [5. Code Structure](#5-code-structure) +- [6. Efficiency and Performance](#6-efficiency-and-performance) +- [7. Error Handling](#7-error-handling) +- [8. Testing](#8-testing) +- [9. Security](#9-security) +- [10. Documentation](#10-documentation) +- [11. Version Control](#11-version-control) +- [12. Scalability](#12-scalability) +- [13. Consistency with Coding Standards](#13-consistency-with-coding-standards) + +## 1. Linting + +You can lint your files locally with: + +```bash +docker compose -f build/docker-compose.linting.yaml up +``` + +### 1.1. Python Linting + +Ensure that all Python files pass linting checks without issues. +Tools such as `black` are already present in this project. +Regular linting ensures that the code adheres to the project's style guide, enhancing readability and maintainability. + +### 1.2. Markdown Linting + +Lint all markdown files with `markdownlint`. + +## 2. Templates + +Follow the guidelines presented in the following templates: + +- [python](templates/template_class.py) +- [markdown](templates/template_wiki_page.md) + +## 3. Python Docstrings The project comes with an extension to automatically generate docstrings. It is mandatory to use it if you comment your code. @@ -27,53 +55,53 @@ Press `Enter` or select the option and it should produce a docstring that looks ![docstring.png](/doc/assets/development/docstring.png) -## Readability and Maintainability +## 4. Readability and Maintainability - **Consistent Formatting:** Code should follow a consistent and readable formatting style. Tools like linters or formatters can help enforce a consistent code style. - [linting](./linting.md) - **Meaningful Names:** Variable and function names should be descriptive and convey the purpose of the code. - **Comments:** Clear and concise comments should be used where necessary to explain complex logic or provide context. -## Code Structure +## 5. Code Structure - **Modularity:** Code should be organized into modular components or functions, promoting reusability and maintainability. - **Appropriate Use of Functions/Methods:** Functions should have a clear purpose and adhere to the single responsibility principle. - **Hierarchy and Nesting:** Avoid overly nested structures; use appropriate levels of indentation to enhance readability. -## Efficiency and Performance +## 6. Efficiency and Performance - **Optimized Algorithms:** Code should use efficient algorithms and data structures to achieve good performance. - **Avoidance of Code Smells:** Detect and eliminate code smells such as duplicated code, unnecessary complexity, or anti-patterns. -## Error Handling +## 7. Error Handling - **Effective Error Messages:** Error messages should be clear and provide useful information for debugging. - **Graceful Error Handling:** Code should handle errors gracefully, avoiding crashes and providing appropriate feedback. -## Testing +## 8. Testing - **Comprehensive Test Coverage:** Code should be accompanied by a suite of tests that cover different scenarios, ensuring reliability and maintainability. - **Test Readability:** Tests should be clear and easy to understand, serving as documentation for the codebase. -## Security +## 9. Security - **Input Validation:** Code should validate and sanitize inputs. -## Documentation +## 10. Documentation - **Code Comments:** In addition to in-code comments, consider external documentation for the overall project structure, APIs, and configurations. - **README Files:** Include a well-written README file that provides an overview of the project, installation instructions, and usage examples. -## Version Control +## 11. Version Control - **Commit Messages:** Use descriptive and meaningful commit messages to track changes effectively. - **Branching Strategy:** Follow a consistent and well-defined branching strategy to manage code changes. -## Scalability +## 12. Scalability - **Avoid Hardcoding:** Parameterize values that might change, making it easier to scale the application. - **Optimized Resource Usage:** Ensure efficient utilization of resources to support scalability. -## Consistency with Coding Standards +## 13. Consistency with Coding Standards - **Adherence to Coding Guidelines:** Follow established coding standards and best practices for the programming language or framework used. diff --git a/doc/development/linting.md b/doc/development/linting.md index 37c6d5ce..bcc9de8a 100644 --- a/doc/development/linting.md +++ b/doc/development/linting.md @@ -1,13 +1,10 @@ # Linting -(Kept from previous group [paf22]) - **Summary:** To ensure unified standards in the project, the following linters are applied during commit. -- [Linting](#linting) - - [🐍 Python conventions](#-python-conventions) - - [💬 Markdown Linter](#-markdown-linter) - - [🚨 Common Problems](#-common-problems) +- [🐍 Python conventions](#-python-conventions) +- [💬 Markdown Linter](#-markdown-linter) +- [🚨 Common Problems](#-common-problems) ## 🐍 Python conventions