Clean Code: Chapter 4 Notes

Sometimes required for copyright/licensing.

Keep them short; refer to standard licenses rather than embedding full legal text.

Explain return values, formats, or patterns.

Prefer naming/structuring code to make such comments unnecessary.

// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

Describe why a certain approach was chosen.

Helps future maintainers understand reasoning behind code.

public int compareTo(Object o)
{
    if(o instanceof WikiPagePath)
        { WikiPagePath p = (WikiPagePath) o;
            String compressedName = StringUtil.join(names, "");
            String compressedArgumentName = StringUtil.join(p.names, "");
            return compressedName.compareTo(compressedArgumentName);
        }
    return 1; // we are greater because we are the right type.
}

Translate obscure values into readable terms.

Useful when working with unchangeable APIs/libraries, but risky if incorrect.

Alert others about performance, thread-safety, or side effects.

For example, in code you can say:

// SimpleDateFormat is not thread safe, so create each instance independently.

Mark incomplete work or planned improvements.

Should be reviewed regularly; not an excuse for bad code.

Highlight the importance of seemingly small details.

// the trim is real important. It removes starting spaces...

Public APIs should have clear documentation.

Javadocs can also mislead. Keep them accurate and up-to-date.

Replace explanatory comments with expressive variable or function names.

Refactor code to remove comment redundancy.

Avoid decorative banners like // Actions ///////////////////////, they add clutter.

Use sparingly and only for meaningful grouping.

Overuse makes them blend into background noise.

Comments on closing braces (} // while) are unnecessary for small, well structured functions.

Prefer short, clear functions over brace markers.

Don’t add personal tags like /* Added by Rick */, use version control for authorship history.

Such comments become outdated and irrelevant over time.

Never keep old code commented out; delete it and rely on version control history.

Commented-out code adds clutter and confuses future maintainers.

// Old cruft that should be deleted:
//hdrPos = bytePos;
//dataPos = bytePos;

Avoid HTML markup inside code comments, it makes them harder to read in the editor.

Let documentation tools (like Javadoc) handle formatting.

Comments should describe nearby code only, not unrelated parts of the system.

Avoid embedding global/system details that the function can’t control.

Avoid long, unnecessary historical or technical explanations.

Keep only relevant context (e.g., “RFC 2045” reference is fine, not the full spec).

Ensure the relationship between comment and code is clear.

Don’t make readers guess what part of the code the comment refers to.

// plus filter bytes ... but which part is “filter”?
this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];

Short, single purpose functions with good names don’t need header comments.

Let the function name explain the purpose.

Javadocs are useful for public APIs, but excessive formality in internal code is just noise.

Internal methods should be self explanatory without full doc comments.