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

Name/Label	Type	Details Provided
Source Code	Text	The complete source code that needs comment improvement.
Programming Language (optional)	Text	The name of the programming language (e.g., Python, Java, C++). If omitted, the language will be detected automatically.

5. Outputs

Name/Label	Contents	Formatting Rules
Revised Source Code	The original code with comments rewritten, added, or removed according to best‑practice guidelines.	Preserve original indentation and line breaks; use the comment syntax appropriate for the identified language.
Comment Improvement Summary	A short report indicating the number of comments added, removed, and rewritten, plus any notable changes.	Plain text; bullet points are acceptable; no special markup required.

6. Detailed Plan & Execution Steps

Collect Inputs – Receive the source code and, if supplied, the programming language.
Identify Language – If the language was not provided, examine file extensions or language‑specific keywords to determine it.
Load Comment Rules – Retrieve the “Comment Best Practices” from Appendix C that apply to the identified language.
Parse the Code – Scan the source line‑by‑line, detecting comment markers based on the language’s syntax (e.g., # for Python, // for Java).
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)?
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.
Apply Changes – Insert, modify, or delete comment lines while preserving the original code formatting and indentation.
Validate Syntax – Run a quick syntax check (e.g., compile‑time parse) to ensure comment markers did not break the code.
Generate Revised Code – Assemble the updated lines into the Revised Source Code output.
Create Summary – Count how many comments were added, removed, and rewritten; note any major clarifications added. Write this information into the Comment Improvement Summary.
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

Explain why, not what:
- Good: “Apply a 5 % discount for bulk orders.”
- Bad: “price = price * 0.95 # apply discount”.
Be concise: Keep comments short but informative; aim for a single sentence when possible.
Use proper grammar and spelling: Treat comments as written communication.
Avoid obvious statements: Do not comment on trivial operations that are self‑explanatory.
Maintain up‑to‑date comments: When code changes, revise related comments immediately.
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

Language	Single‑Line Marker	Multi‑Line Delimiters
Python	`#`	N/A (use consecutive `#` lines)
Java	`//`	`/* … */`
C++	`//`	`/* … */`
JavaScript	`//`	`/* … */`
C#	`//`	`/* … */`
Ruby	`#`	`=begin` / `=end`
Go	`//`	`/* … */`
PHP	`//` or `#`	`/* … */`

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.)

Header Comment Block (for files):

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

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.
    """

Inline Comment Formatting:
- Begin with a capital letter.
- No trailing period for short comments.
- Keep within 80 characters when possible.

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.

Line Number	Original Comment	Revised Comment
1	#calc area	Calculate the area of a circle.
2	#return the area	Return the area of a circle given its radius.
3	# compute area	Compute the area of a circle.

Upgrade Code Comments, Accelerate Development