Code comments

Question: Does a comment only repeat its code, hold sentences that add nothing, narrate an edit instead of the code as it is, or hold code turned off?

• Runs: when selected: --rule comments, --rule documentation or --rule all · Fails the check by default: no
• Right on projects JevGate was never tuned on: considers 54% (39 of 72) (how it is measured)
• Right on the projects it was tuned on: considers 65% (97 of 150)
• Looks at: comments and docstrings of application code, except license headers, tool directives and type annotations
• Evidence unit: one comment with the code it is about: the declaration it documents, the lines below it or the line it ends; then the whole definition it sits in
• Acceptable: Reasons, constraints, caveats, references, and documentation of what a definition returns or guarantees beyond its signature
• Names: documentation/comments, comments, comments · Version: 3

When a finding is right

A finding says a comment only repeats its code, holds sentences that add nothing, narrates an edit instead of describing the code as it is, or is code turned off. It is right for # Create skill directory above skill_dir.mkdir(…), or a docstring saying a module was split out to stay under a line budget. It is wrong when the comment heads a step of a long function, gives a reason, or, in a teaching project, is the lesson itself. A third of the findings labeled wrong or debatable outside Bend 2 code were step headings.

A comment still undecided once its kind is asked leans on the kind, and the comments of one definition that span fewer than three lines in all are a note.

Findings it got wrong

Labeled wrong by reading the code, on open-source projects the rules were tuned on.

LinkAce: config/auth.php

• Where: config/auth.php:95 in Kovah/LinkAce at d682166.
• Finding (consider): This file’s top-level code has a comment to clean up: at lines 95–98 it repeats the code.
• Why it was wrong: The lines are the Laravel skeleton’s own example of a database user provider beside the active eloquent one, under a header listing both drivers. The framework publishes the file with its documentation; removing its examples gains nothing.
• Since: cleared in 0.20.0, which no longer reads a Laravel application’s config/*.php files for comments (changelog).

httpx: urlparse

• Where: httpx/_urlparse.py:234 in encode/httpx at b5addb6.
• Finding (consider): urlparse has 5 comments to clean up: at lines 234, 244, 250 and 284 they repeat the code; at line 239 it narrates an edit instead of the code as it is.
• Why it was wrong: The comments head the steps of a 130-line function divided by comment banners. Line 239, # Replace "netloc" with "host and "port"., says what the code does to its arguments when it runs, not a past edit.
• Since: not addressed; reported the same way from 0.19.0 through 0.25.0.

NodeGoat: the route table

• Where: app/routes/index.js:40 in OWASP/NodeGoat at c5cb68a.
• Finding (consider): index has 3 comments to clean up: at lines 40 and 78 they repeat the code; at lines 57–60 it is code turned off.
• Why it was wrong: NodeGoat teaches web security. Lines 57–60 are the commented-out “Fix for A7”, the routes with the missing role check, kept as the exercise’s answer; lines 40 and 78 head entries of a route table like the others.
• Since: not addressed; reported the same way from 0.19.0 through 0.25.0.