WIP: Code comments standard

docs/standards/code-comments.md

@@ -0,0 +1,339 @@
+---
+layout: standard
+order: 1
+title: Code Comments
+date: 2023-10-18
+id: SEGAS-TBC
+tags:
+  - Documentation
+  - Ways of working
+related:
+  sections:
+    - title: Related links
+      items:
+        - text: Minimal documentation set for a product
+          href: /standards/minimal-documentation-set-for-a-product/
+---
+
+These Code Commenting Guidelines are designed to ensure that code is documented at a minimum standard, making it easy for new engineers to quickly get up to speed and preventing the isolation of knowledge within the team. By following these guidelines, you help streamline the onboarding process for new team members, ensuring that code is accessible and understandable. 
+
+This standard promotes effective communication and knowledge sharing within the team, ultimately contributing to the overall success of the project.
+
+---
+
+## Requirement(s)
+
+- [Comments MUST enhance code comprehension and maintainability.](#comments-must-enhance-code-comprehension-and-maintainability)
+- [Comments MUST be explanatory, not merely descriptive, and use concise, fully-formed sentences.](#comments-must-be-explanatory-not-merely-descriptive-and-use-concise-fully-formed-sentences)
+- [Comments MUST add value to the understanding and readability of the code.](#comments-must-add-value-to-the-understanding-and-readability-of-the-code)
+- [Comments MUST adhere to a documented standard, such as Docblock, and include all necessary information.](#comments-must-adhere-to-a-documented-standard-such-as-docblock-and-include-all-necessary-information)
+- [Comments MUST Remain Applicable After Code Refactor.](#comments-must-remain-applicable-after-code-refactor)
+- [Comments MUST Use Neutral, Unopinionated Language.](#comments-must-use-neutral-unopinionated-language)
+- [Comments MUST NOT be present in production deployments.](#comments-must-not-be-present-in-production-deployments)
+- [Comments MUST NOT be used as a substitute for deleting code.](#comments-must-not-be-used-as-a-substitute-for-deleting-code)
+- [Comments MUST NOT contain sensitive data, such as API keys, tokens, etc.](#comments-must-not-contain-sensitive-data-such-as-api-keys-tokens-etc)
+
+### Comments MUST enhance code comprehension and maintainability.
+
+The placement of comments is essential for code comprehensibility and maintainability. Comments should be thoughtfully positioned to explain complex logic, significant decision points, or any non-trivial functionality.
+
+Positioning comments at the top of files, above structural elements, or before specific code sections assists both newcomers and existing team members in understanding the code's purpose. This fosters a collaborative environment, ensuring seamless knowledge transfer and facilitating effective contributions from colleagues to the project.
+
+#### Positive Example
+```
+"""
+Calculates the total price of items in the shopping cart by summing up individual item prices.
+
+This function iterates through each item in the provided shopping cart, extracting the 'price'
+attribute from each item, and aggregating these prices to compute the overall total.
+
+:param cart: A list of items in the shopping cart. Each item should be an object or instance
+             with a 'price' attribute representing the cost of that particular item.
+:return: The total price as a floating-point number, representing the sum of individual item prices.
+"""
+def calculate_total_price(cart):
+    total_price = 0.0
+    for item in cart:
+        total_price += item.price
+    return total_price
+```
+
+#### Negative Example
+```
+def calculate_total_price(cart):
+    # This function calculates the total price
+    total_price = 0.0
+    for item in cart:
+        total_price += item.price
+    return total_price
+```
+
+### Comments MUST be explanatory, not merely descriptive, and use concise, fully-formed sentences.
+
+The use of language in your comments is essential for effective communication. Comments should serve the purpose of explaining the reasoning behind the code rather than solely describing its functionality. They should be clear, concise, and composed of fully-formed sentences.
+
+This practice ensures that readers can grasp the code's intent without any ambiguity. Concise and explanatory comments contribute to enhanced code readability and easier maintenance.
+
+Additionally, adhere to the DRY (Don't Repeat Yourself) principle. Avoid duplicating comments that describe similar logic in different parts of the code. Instead, use well-crafted comments in one location to cover shared concepts or functionalities. This not only reduces redundancy but also promotes consistency and helps prevent inconsistencies or contradictions in your documentation.
+
+#### Positive Example
+```
+"""
+Calculates the factorial of a given integer.
+
+
+:param n: The non-negative integer for which to calculate the factorial.
+:return: The factorial of the input integer.
+"""
+def calculate_factorial(n):
+    if n < 0:
+        return "Input must be a non-negative integer."
+    elif n == 0:
+        return 1
+    else:
+        factorial = 1
+        for i in range(1, n + 1):
+            factorial *= i
+        return factorial
+```
+
+#### Negative Example
+```
+"""
+This function computes the factorial of an integer, n.
+
+This function takes an integer, n, as input and calculates its factorial. The factorial is calculated for any non-negative integer, denoted as n!, which is found by multiplying all the positive integers less than or equal to n. If the input, n, is negative, an error message is returned. Otherwise, the factorial is calculated using a loop.
+
+:param n: An input integer, which should be a non-negative integer.
+:return: The output of the function is the factorial of the provided integer.
+"""
+def calculate_factorial(n):
+    if n < 0:
+        return "An error has occurred. The input should be a non-negative integer."
+    elif n == 0:
+        return 1
+    else:
+        factorial = 1
+        for i in range(1, n + 1):
+            factorial *= i
+        return factorial
+```
+
+### Comments MUST add value to the understanding and readability of the code.
+
+Comments that provide value are essential for code documentation. Comments should not be added thoughtlessly but should genuinely enhance the codebase.
+
+Each comment should contribute to the reader's understanding of the code by providing insights or explanations that might not be immediately evident from the code itself. Value-added comments act as a bridge between the code's functionality and the developer's comprehension, improving accessibility and efficiency for both current and future team members.
+
+Additionally, consider that code functions should be written in a way that allows developers to use them effectively without having to delve into the source code. This means that function signatures, parameter names, and return types should be self-explanatory. Well-crafted comments can complement this by offering high-level explanations or usage examples, making it possible for developers to utilize functions blindly, confidently relying on the documented behavior without necessarily needing to inspect the implementation details.
+
+#### Positive Example
+```
+"""
+This function validates user passwords.
+
+This function takes a password as input and checks if it meets security requirements, including minimum length, the presence of both uppercase and lowercase letters, and the use of special characters.
+
+:param password: The user's input password.
+:return: True if the password meets security requirements, False otherwise.
+"""
+def validate_password(password):
+    ...
+```
+
+#### Negative Example
+```
+"""
+This function validates user passwords.
+
+:param password: The user's input password.
+:return: True if the password is valid, False if it's not.
+"""
+def validate_password(password):
+    ...
+```
+
+### Comments MUST adhere to a documented standard, such as Docblock, and include all necessary information.
+
+Adhering to a documented standard in your comments can assist in achieving consistency and comprehension. Following established standards, like Docblock, helps harmonize the commenting style across the codebase, simplifying navigation and comprehension for all team members.
+
+Furthermore, comments should encompass all pertinent information, including parameter descriptions, return values, and function or class explanations. This practice ensures that any developer reviewing the code possesses all the necessary details to use, modify, or maintain it effectively, reducing the necessity for time-consuming back-and-forths or investigations.
+
+When developing APIs, comments play a crucial role in generating API documentation automatically. Systems like Swagger, which rely on comments within the code, can extract valuable information and generate comprehensive API documentation. By consistently using Docblock or similar standards, developers contribute not only to the clarity of the code but also to the seamless generation of API documentation. This documentation becomes an invaluable resource for users and maintainers, facilitating easier integration and understanding of the API's capabilities.
+
+### Swagger Information
+- [Swagger](https://swagger.io/)
+
+#### Docblock Information
+- [Docblock - Wikipedia](https://en.wikipedia.org/wiki/Docblock)
+
+##### Language Specific Links (for reference only)
+- [JavaDoc](https://www.oracle.com/uk/technical-resources/articles/java/javadoc-tool.html)
+- [JSDoc](https://developer.adobe.com/commerce/php/coding-standards/js-docblock/)
+- [TSDoc](https://tsdoc.org/)
+- [Python Doc String](https://pandas.pydata.org/docs/development/contributing_docstring.html)
+
+#### Positive Example
+```
+"""
+Calculates the factorial of a given integer.
+
+This function takes an integer as input and returns its factorial. The factorial of a non-negative integer n, denoted as n!, is the product of all positive integers less than or equal to n.
+
+:param n: The non-negative integer for which to calculate the factorial.
+:return: The factorial of the input integer.
+"""
+def calculate_factorial(n):
+    ...
+```
+
+#### Negative Example
+```
+"""
+Calculate factorial, takes a param called `n` which is a number to compute the returned factorial.
+"""
+def calculate_factorial(n):
+    ...
+```
+
+### Comments MUST Remain Applicable After Code Refactor
+
+Ensuring that comments remain relevant after code refactors is crucial for long-term code sustainability. Comments should retain their relevance even after code refactors or modifications. This practice ensures that the information conveyed in the comments remains accurate and valuable as the codebase undergoes changes. By doing so, the risk of confusion and errors during future modifications is significantly reduced.
+
+#### Positive Example
+```
+"""
+Calculates the total price of items in the shopping cart.
+
+This function computes the total price by iterating through the items in the shopping cart and summing their prices.
+
+:param cart: List of items in the shopping cart.
+:return: Total price as a float.
+"""
+```
+
+#### Negative Example
+```
+"""
+This function is optimized for small shopping carts with less than 10 items.
+
+This function is specifically designed for small shopping carts with less than 10 items. It uses an efficient algorithm that may not be suitable for larger carts.
+
+:param cart: List of items in the shopping cart.
+:return: Total price as a float.
+"""
+```
+
+### Comments MUST Use Neutral, Unopinionated Language
+
+Comments should use neutral, unopinionated language to ensure clarity and avoid subjective interpretations. Expressions of personal opinions, unwarranted enthusiasm, or assertions of superiority should be avoided. The goal is to provide factual and clear explanations that facilitate understanding.
+
+#### Positive Example
+```
+"""
+Calculates the total price of items in the shopping cart.
+
+This function takes a shopping cart as input and calculates the total price. It iterates through the cart items and sums their prices. The code is designed to work efficiently with various cart structures.
+
+:param cart: The shopping cart as a list of items.
+:return: The total price as a float.
+"""
+```
+
+#### Negative Example
+```
+"""
+This function calculates the total price in a smart way.
+
+This function takes a list of items as input and computes the total price in a highly efficient manner. It's the best way to do this, and it's really smart. You'd be crazy to change it.
+
+:param items: The list of items.
+:return: The total price, and trust me, it's the best way to do it.
+"""
+```
+
+### Comments MUST NOT be present in production deployments.
+
+Comments in production deployments present potential security and performance risks. They can unintentionally expose sensitive information, such as API keys or debugging details, to unauthorized individuals. Additionally, comments may have a marginal impact on the code's size, which can affect performance in production environments.
+
+It is important to ensure that no comments are included in production code to mitigate these issues. The removal of comments from production code enhances security and optimizes code performance, ultimately leading to an improved user experience.
+
+Furthermore, note that some modern compilers and build tools may automatically strip comments from the compiled code during the production build process. While relying on automatic tools, it is still crucial for developers to follow best practices and ensure that no sensitive information or unnecessary comments are present in the codebase, even before the build process.
+
+#### Tools (for reference only)
+- **React/JavaScript/TypeScript/Node:**
+  - [Terser](https://terser.org/)
+  - [Babel](https://babeljs.io/)
+
+- **HTML/CSS:**
+  - [HTML Minifier](https://www.npmjs.com/package/html-minifier)
+  - [CSS Minifier](https://www.npmjs.com/package/css-minify)
+
+#### Example
+No example given.
+
+### Comments MUST NOT be used as a substitute for deleting code.
+
+Duplication of comments and using comments as a replacement for code deletion can impact code cleanliness. Developers are encouraged to steer clear of duplicating comments across various code sections, as it may result in inconsistencies when modifications are required. Rather than adding a comment to explain outdated or unnecessary code, it is advisable to remove the unused code entirely.
+
+Replacing code deletion with comments can introduce confusion and clutter within the codebase. Ensuring that comments are employed for authentic explanations and not as a workaround for code removal contributes to a cleaner and more maintainable codebase.
+
+#### Positive Example
+```
+"""
+This function calculates the area of a rectangle.
+
+:param length: The length of the rectangle.
+:param width: The width of the rectangle.
+:return: The area of the rectangle.
+"""
+def calculate_rectangle_area(length, width):
+    return length * width
+```
+
+#### Negative Example
+```
+"""
+This function calculates the area of a rectangle.
+
+:param length: The length of the rectangle.
+:param width: The width of the rectangle.
+:return: The area of the rectangle.
+"""
+def calculate_rectangle_area(length, width):
+    # Calculate the area of the rectangle
+    return length * width
+    # return width * length # Not used
+```
+
+### Comments MUST NOT contain sensitive data, such as API keys, tokens, etc.
+
+Avoiding sensitive data in comments is a fundamental security practice. Storing confidential information, such as API keys or tokens, within comments can pose substantial security risks. Comments are typically part of the source code repository and may be accessible to unauthorized individuals.
+
+To safeguard sensitive data and maintain the security of your application, it's essential to refrain from including such information within comments. Instead, it's advisable to utilize secure and designated storage mechanisms for sensitive data, guaranteeing the functionality and security of your code.
+
+#### Good Example
+```
+"""
+Connect to the database using secure credentials.
+
+This function establishes a database connection using secure credentials stored in a separate, protected configuration file. Sensitive data, such as database usernames and passwords, are not exposed in comments or within the source code.
+
+:return: A database connection object.
+"""
+def connect_to_database():
+    # Database connection logic here
+```
+
+#### Bad Example
+```
+"""
+Connect to the database using username 'my_user' and password 'my_password'.
+
+This function establishes a database connection using hard-coded sensitive data within the comment itself. Storing sensitive data in this manner is a security risk and should be avoided.
+
+:return: A database connection object.
+"""
+def connect_to_database():
+    # Database connection logic here
+```