Code Comment Improver

1. Overview

The Code Comment Improver takes a block of source code and rewrites, adds, or removes comments so that they are clear, concise, and useful for future readers. It leaves the functional code unchanged while making the documentation inside the code easier to understand.

2. Business Value

• Improved readability: Clean comments help developers grasp intent quickly.

• Reduced maintenance cost: Clear documentation lowers the time spent deciphering legacy code.

• Higher quality reviews: Reviewers spend less time on trivial comment issues and can focus on logic.

• Consistent style: Aligns the team around a shared commenting standard, reducing friction.

3. Operational Context

• When to run:

  • Before a code review where comment quality is a focus.

  • During a refactor or when onboarding new team members.

  • When a repository’s comment guidelines have been updated.

• Who uses it: Software Engineers, Team Leads, Technical Writers.

• How often: As needed, typically per feature branch or per file that receives significant changes.

4. Inputs

5. Outputs

6. Detailed Plan & Execution Steps

1. Collect Inputs – Receive the source code and, if supplied, the programming language.

2. Identify Language – If the language was not provided, examine file extensions or language‑specific keywords to determine it.

3. Load Comment Rules – Retrieve the “Comment Best Practices” from Appendix C that apply to the identified language.

4. Parse the Code – Scan the source line‑by‑line, detecting comment markers based on the language’s syntax (e.g., # for Python, // for Java).

5. Evaluate Each Comment – For every detected comment:

   • Relevance Check: Does the comment explain why something is done, or does it merely restate what the code already says?

   • Clarity Check: Is the wording clear, free of slang, and grammatically correct?

   • Redundancy Check: Is the comment stating the obvious (e.g., “increment i” next to i += 1)?

6. Decide Action – Based on the evaluation:

   • Rewrite a comment that is relevant but unclear or wordy.

   • Add a new comment before any code block that is complex, non‑obvious, or implements a business rule.

   • Remove a comment that is redundant, outdated, or merely duplicated code.

   • Preserve TODO/FIXME notes unchanged, but ensure they follow the required format.

7. Apply Changes – Insert, modify, or delete comment lines while preserving the original code formatting and indentation.

8. Validate Syntax – Run a quick syntax check (e.g., compile‑time parse) to ensure comment markers did not break the code.

9. Generate Revised Code – Assemble the updated lines into the Revised Source Code output.

10. Create Summary – Count how many comments were added, removed, and rewritten; note any major clarifications added. Write this information into the Comment Improvement Summary.

11. Deliver Outputs – Provide both the Revised Source Code and the Summary to the requester.

7. Validation & Quality Checks

• Syntax Validation: Ensure the revised file compiles or parses without errors related to comment syntax.

• Change Isolation: Verify that only comment lines were altered; all functional code lines remain identical to the input.

• Relevance Confirmation: Randomly sample a few rewritten or added comments to confirm they explain why the code does something, not what it does.

• Redundancy Scan: Check that no remaining comment repeats the code verbatim.

• Formatting Consistency: Confirm that comment indentation matches surrounding code and that line lengths respect any style limits in Appendix C.

8. Special Rules / Edge Cases

• Commented‑Out Code: If an entire block is commented out and not marked as TODO/FIXME, treat it as redundant and remove the comment markers.

• Multi‑Line Comments: Preserve block comment delimiters (e.g., /* … */) and apply the same evaluation rules to each line inside.

• Language Detection Failure: If the language cannot be confidently identified, halt processing and return an “Unable to determine language – manual review required” status.

• Non‑English Comments: Leave non‑English comments untouched unless they are clearly redundant; flag them for a separate translation review.

• Documentation Links: Keep hyperlinks if they point to active documentation; if the link is broken, note it in the summary.

• TODO/FIXME Preservation: Do not delete TODO, FIXME, or similar markers; only adjust formatting if needed.

9. Example

Input

• Source Code (Python)

def calculate_total(price, tax):
    # calculate total price
    total = price + tax  # add tax to price
    return total  # return the total amount

• Programming Language: Python

Output

• Revised Source Code

def calculate_total(price, tax):
    # Compute the final amount including tax.
    total = price + tax
    return total

• Comment Improvement Summary

• Comments added: 1

• Comments removed: 2 (removed “calculate total price” and “add tax to price” because they restated the code)

• Comments rewritten: 0

• Major change: Added a concise comment that explains the purpose of the function rather than restating each line.

Appendix A – FAQ

• Q: Will the process ever change the actual code? A: No. Only comment lines are modified; all functional statements remain untouched.

• Q: My code uses a custom comment marker. Can it be handled? A: The process supports the standard comment syntaxes listed in Appendix C. For unusual markers, supply the marker as part of the “Programming Language” input or add a note in the source file’s header.

• Q: How does the tool handle very long functions? A: It focuses on comments that are directly attached to code lines. If a function exceeds typical length guidelines, a high‑level comment summarizing its purpose may be added at the top.

• Q: What if a comment contains a typo that changes its meaning? A: The comment will be rewritten to correct spelling and improve clarity while preserving the original intent.

• Q: Can I keep an existing good comment? A: Yes. Comments that already follow best practices are left unchanged.

Appendix B – Glossary

• Comment: Non‑executable text inserted in source code to explain, clarify, or annotate the code.

• TODO / FIXME: Standard markers used to flag unfinished work or known issues.

• Redundant Comment: A comment that repeats exactly what the code line already says.

• Relevance: The extent to which a comment adds useful information beyond the code itself.

• Syntax Check: A quick verification that the source file still conforms to the language’s grammar rules after comment changes.

Appendix C – Comment Best Practices

General Principles

1. Explain why, not what:

   • Good: “Apply a 5 % discount for bulk orders.”

   • Bad: “price = price * 0.95 # apply discount”.

2. Be concise: Keep comments short but informative; aim for a single sentence when possible.

3. Use proper grammar and spelling: Treat comments as written communication.

4. Avoid obvious statements: Do not comment on trivial operations that are self‑explanatory.

5. Maintain up‑to‑date comments: When code changes, revise related comments immediately.

6. Consistent style: Follow the team’s chosen comment format (e.g., start with a capital letter, end without a period for short tags).

Language‑Specific Syntax

TODO / FIXME Guidelines

• Format: TODO: description or FIXME: description.

• Placement: On its own line or at the end of a relevant code line.

• Actionability: Provide enough detail for another developer to understand the needed work.

Comment Placement

• Function / Method Header: Briefly describe purpose, inputs, outputs, and side effects.

• Complex Logic Block: Insert a comment before the block explaining the algorithmic intent.

• One‑Liner Clarifications: Place on the line directly above or at the end of the line, using the language’s single‑line marker.

Prohibited Comment Types

• Redundant Restatements (e.g., “i = i + 1 // increment i”).

• Outdated Information (e.g., references to removed features).

• Sensitive Data (e.g., passwords, API keys).

Review Checklist

• Does each comment add value?

• Are all comments grammatically correct?

• Are comment markers correct for the language?

• Are TODO/FIXME notes properly formatted?

• Have any redundant comments been removed?

Appendix D – Sample Comment Style Guide

(This appendix provides a concrete style template that teams can copy into their own documentation repositories.)

1. Header Comment Block (for files):

   # ----------------------------------------------------------------------
   # File: <filename>
   # Description: <Brief description of the file’s purpose>
   # Author: <Name>
   # Created: <Date>
   # ----------------------------------------------------------------------
   

2. Function Header (Python Example):

   def fetch_user(id):
       """
       Retrieve a user record from the database.
   
       Parameters:
           id (int): Unique identifier of the user.
   
       Returns:
           dict: User data if found, otherwise None.
       """
   

3. Inline Comment Formatting:

   • Begin with a capital letter.

   • No trailing period for short comments.

   • Keep within 80 characters when possible.

4. Multi‑Line Block Comment (Java Example):

   /*
    * Validate input parameters before proceeding.
    * Throws IllegalArgumentException if any parameter is null.
    */
   

By following the steps, checks, and guidelines above, the Code Comment Improver consistently produces clearer, more maintainable source code without altering its behavior.