Clean Code Comments & Docstrings

Built around how developers read code

• Clearer comments

  Say what the code does instead of restating the syntax.

• Readable documentation

  Docstrings that a teammate can skim in a second.

• Consistent wording

  One voice and tense across a file or module.

• Better explanations

  Edge cases and intent spelled out where it matters.

Only the comments change

# this func take the list and do the calculation of avg
# returns avg
def average(values):
    return sum(values) / len(values)

# Return the arithmetic mean of the given values.
# Raises ZeroDivisionError when the list is empty.
def average(values):
    return sum(values) / len(values)

The function body is byte-for-byte identical in both panels.

Use cases

Generated code documentation, legacy comments that drifted from the code, inconsistent docstrings across a module, and internal developer documentation drafts.

How it works

1. 1

   Select Clean Code Comments.

2. 2

   Provide the code with its comments or docstrings.

3. 3

   Review the refined documentation and keep what fits.

Developer questions