Commenting & Documentation

Commenting and Documentation

Definition

Comments are in-code annotations that clarify why or how certain logic works, without altering the program’s runtime behavior.
Documentation refers to more formal or generated descriptions (like XML docs in C#, JavaDocs in Java, docstrings in Python, or Markdown files) that help users or maintainers understand a module’s purpose, API, and usage.

“Good code is its own best documentation” – Steve McConnell
Yet, strategic documentation and comments remain invaluable when explaining non-obvious decisions or architectural overviews.

---

Why It Matters

1. Readability
   • Clear comments help developers (including your future self) quickly grasp the intent behind complex or less obvious segments of code.
2. Maintainability
   • Accurate documentation and comments reduce friction when updating or refactoring. Developers can see how everything fits together without reverse-engineering logic.
3. Collaboration
   • In multi-developer teams, consistent commenting styles and thorough documentation ensure shared understanding, reducing onboarding time and confusion.
4. Knowledge Transfer
   • When a key developer leaves, well-documented code softens the knowledge gap for new or remaining team members.
5. User-Facing Clarity
   • Libraries and frameworks rely heavily on good docs (e.g., docstrings, README files) so external consumers can integrate and use them effectively.

---

Examples & Best Practices

Using C#-style examples, but these principles apply to nearly any language.

1. Code Comments

• Explain the “Why,” Not the “What”

  // BAD: This comment merely restates the code
  int total = orderList.Count; // get the count of orders
  
  // GOOD: Explains reasoning behind a decision or approach
  // The order list is guaranteed to have at least one item based on prior validation.
  int total = orderList.Count;

• Highlight Edge Cases or Workarounds

  // The external API can return null if the item doesn't exist, so handle that case here
  var result = ExternalService.GetItemById(id);

• Keep Comments Up-to-Date

  • If the code changes but the comment remains outdated, it causes confusion.
    
  • Regularly review or refactor comments alongside code.

2. Method/Class-Level Documentation

• XML Comments (C#)

  /// <summary>
  ///  Processes an order by validating its items, calculating totals, and updating the database.
  /// </summary>
  /// <param name="order">The order to be processed.</param>
  /// <returns>Returns true if the process succeeds; otherwise false.</returns>
  public bool ProcessOrder(Order order)
  {
      // Method logic
  }

• JavaDoc (Java)

  /**
   * Processes an order by validating its items, calculating totals, 
   * and updating the database.
   *
   * @param order the order to be processed
   * @return true if the process succeeds; otherwise false
   */
  public boolean processOrder(Order order) {
      // Method logic
  }

• Docstrings (Python)

  def process_order(order):
      """
      Processes an order by validating its items, calculating totals,
      and updating the database.
  
      :param order: The order to be processed
      :returns: True if the process succeeds; otherwise False
      """
      # Function logic

3. High-Level Documentation

• README / Markdown Files
  • Include an overview of the project, setup instructions, usage examples, and contribution guidelines in a README.md.
• Architecture Docs
  • Larger systems benefit from diagrams and architectural overviews (e.g., in docs/ folder or a wiki).
• API Docs
  • For public APIs, auto-generate docs from doc comments (e.g., with Doxygen, Swagger, or DocFX).

4. Comment and Documentation Guidelines

1. Consistency
   • Use a standard format for doc comments (e.g., XML docs in C#, JavaDoc in Java).
     
   • Keep style consistent across the team/project.
2. Brevity and Clarity
   • Make comments/doc descriptions concise yet informative.
     
   • Avoid long-winded paragraphs unless absolutely necessary.
3. Avoid Redundancy
   • Don’t duplicate code in the comment. Instead, clarify logic, rationale, or usage.
     
   • If the code is already self-explanatory, skip the comment.
4. Document Public APIs Thoroughly
   • Public-facing methods, libraries, or endpoints need especially clear documentation for external consumers.
5. Update Alongside Code Changes
   • Treat comments/docs as part of the code. When refactoring, revise or remove outdated documentation.

---

Conclusion

Commenting and documentation are essential tools for ensuring your codebase remains readable, maintainable, and welcoming to both existing and future developers. While well-structured, self-describing code should reduce the need for excessive comments, strategic in-code annotations and comprehensive reference docs (like docstrings or Markdown files) fill in the gaps that code alone cannot convey. By keeping your documentation accurate, concise, and in sync with evolving requirements, you create a robust foundation for continuous growth and collaboration in your software project.