I am proposing a commenting style guideline. This is not initially meant to be a unique commenting guide.
The story behind its creation arises from the usage of Large Language Models (LLMs) for code generation. The generated codes are indeed usually oververbose in commenting lines (excessive comment-to-code ratio). To address this issue, I once thought I should have a set of rule-based constraints that I could inject into the LLM’s context before asking for code generation. I wanted the set of rules to help provide code commented in a minimal and complete way. The set of rules did not exist at first so I experimented and ended up with creating one, that I am providing below.
After that, I also reminded my first days of coding when I asked myself “Where to find a guideline to write good comments ?”, and I realized this was one answer.
(Additionally, I think it can be further improved regarding constraints of the generated docstrings, but this question might as well be considered out of scope, as PEP 257 already provides docstring conventions.)
I think it can be useful to some people, thus it has some value, maybe enough to provide a basis for a new PEP. I’m curious about the opinions and feedback the python community can have about it.
# Essential Contextual Code Commenting
This document outlines the essential rules for effective code commenting, aimed at improving code readability and maintainability. Following these guidelines will help ensure that comments enhance understanding without cluttering the code.
## 1. Self-Explanatory Code is better
- **Meaningful Names**: Ensure that variable and function names are descriptive enough to convey their purpose.
- **Logical Structure**: Organize the code in a clear, logical manner that follows a consistent flow.
## 2. Shorter Comments are better
- **Focus on Key Concepts**: Highlight external concepts or important decisions that may not be immediately obvious from the code.
- **Avoid Redundancy**: Do not repeat information that can be easily inferred from the code itself.
- **Be Concise**: Keep comments short and impactful while ensuring they remain clear and informative.
## 3. Instances Have Purposes (Inline Comments)
- **Element Purpose**: Describe the purpose of variables as inline comments. Name the external concepts they are defined from, if any.
- **Explain Important Variables**: Provide brief explanations for key variables when they represent complex concepts or calculations, especially if they are not immediately intuitive.
- **Consistency**: Ensure that inline comments are directly relevant to the code they annotate.
## 4. Functions Have Flow (Outline Comments)
- **Docstring as Overview**: Use the function docstring to provide an overview of what the code does and its purpose within the larger application.
- **Structure Description (Outline Comments)**: Use outline comments to summarize the main processing steps involved in the function, indicating the sequence of operations being performed by significant sections or blocks of code.
- **Coherency**: Ensure that comments follow a clear logical structure to enhance readability.
## 5. Document Assumptions and Limitations
- **Clarify Assumptions**: If there are assumptions about inputs or outputs, document these clearly to help future maintainers understand potential pitfalls.
- **Highlight Limitations**: Note any limitations of the code or areas where further development may be needed.