Clean Code in Practice: Writing Helpful Documentation for Developers

Glossary

Documentation Written guidance that explains code for other developers or for future reference.

Docstring / Javadoc Structured, standardized documentation placed inside functions, classes, or methods to explain how to use them (inputs, outputs, behavior).

Code Comment Notes placed inside code to explain why something is done, not what the code literally does.

User Manual Documentation focused on how to use a piece of code or an interface - the "how to call it" guide.

Assembly Plans Developer-focused documentation that explains design decisions, internal structure, and reasoning behind code.

---

Good documentation is part of clean code. It helps others (and your future self) understand what your code does and how to use it — without having to read every line. But not all comments are equal. In Project Work, we focus on two kinds of documentation that serve two different audiences of developers.

User Manual vs Assembly Plans

Think of your codebase like a product. The user manual is what guides someone who wants to use it — short, clear, and focused on the interface: what buttons to press, what inputs to give, and what results to expect. That’s your docstrings or Javadoc.

The assembly plans, on the other hand, are for the people building or maintaining it. They explain why certain parts are shaped the way they are, how the pieces fit together, and what to avoid breaking. Those are your inline comments.

Both are valuable — but they have different audiences. A user doesn’t want to read wiring diagrams, and a technician doesn’t want fluffy marketing text. Mixing them confuses everyone.

Code Comments — For the Builder

Code comments are for the developer who writes or maintains the code. They explain why something is done a certain way — not what it does. The “what” should already be clear from readable names and structure.

Example

# We cache results because computing the hash takes ~2s on large files
cache[file_path] = compute_hash(file_path)

Here the code itself shows what happens; the comment explains why.

Danger

Avoid comments that just repeat the code:

# increment counter
count += 1

Think of comments as temporary crutches. Uncle Bob (Clean Code) calls them “a necessary evil.” Every time you write one, ask yourself if you could instead make the code clearer through naming or refactoring.
Good comments add reasoning. Bad comments apologize for messy code.

Docstrings / Javadoc — For Who Uses It

Docstrings or Javadocs are for the developer who calls your code, not for the one who wrote it. They describe the interface — what the method or class offers, what inputs it expects, and what outputs or side effects it has.

Example

def resize(image, width, height):
    """
    Resize an image to the given width and height.

    Args:
        image (Image): the image to resize
        width (int): target width in pixels
        height (int): target height in pixels

    Returns:
        Image: the resized image
    """

This is like the “user manual” for the method — not a peek under the hood.

In Java:

/**
 * Calculates the average score of all students in the list.
 * @param scores List of integer scores.
 * @return The average as a double. Returns 0 if the list is empty.
 */
public double calculateAverage(List<Integer> scores) { ... }

Tip

Write docstrings before implementation if possible — it helps clarify intent and edge cases early.

When to Use Which

Purpose	Audience	Describes	Example
Code comment	You or teammates maintaining code	The “why” behind a non-obvious decision	# avoid recursion here to prevent stack overflow
Docstring / Javadoc	Anyone using the code	The “how to use” interface: parameters, return values, exceptions	@param, @return, examples of usage

Good Comment Types

Type	Purpose	Example
Legal Comments	Add required legal or licensing info	// Copyright (c) 2025 CompanyName. All rights reserved.
Informative Comments	Explain intent, format, or meaning when it’s not clear from code	// Returns list of employees ordered by start date
Explanation of Intent	Clarify why something is done in a non-obvious way	// We use a lookup table here for speed — avoids recalculating each time
Clarification of Meaning	Make code logic clearer for future readers	// Threshold chosen based on usability test results
Warning of Consequences	Warn others about dangerous side effects or limitations	// Don’t delete this file unless you know what depends on it
TODO Comments	Mark future work or known issues (when tracked and temporary)	// TODO: replace hardcoded values after config module ready
Amplifying Comments	Strengthen the understanding of a design choice	// Using static instance ensures only one logger per app
API Documentation (Docstrings / Javadoc)	Describe how to use a class or function (parameters, return, exceptions)	/** Calculates average; returns 0 if empty */

Bad Comment Types

Type	Problem	Example
Mumbling Comments	So vague they add no value	// update stuff
Redundant Comments	Restate what code already says	// set x to 5
Misleading Comments	Outdated or wrong, causing confusion	Comment says “sorted”, but code doesn’t
Mandated Comments	Forced per-function headers that repeat names	// This is a contructor above def __init__(x, y)
Journal / Log Comments	Historical edits that belong in version control	// 2023-10-02: fixed bug by John
Noise	Decorative banners or filler	// ====== START ======
Scary TODOs	Permanent TODOs that never get done	// TODO: fix later (3 years old)
Misplaced Information	Comments describing external systems or irrelevant context	// This works because the finance server uses MySQL
Obvious Comments	Restate self-explanatory logic	// loop over list
Closing Brace Markers	unnecessary with proper indentation	// end if, // end for
Commented-Out Code	Old code left “just in case” — should be deleted	// if (x == 1) doSomething();
Nonlocal Comments	Describing something far away in the code	// modifies global state (but not near that code)

Practical Advice

• Write docstrings for public functions, classes, and modules — anything others might reuse.
• Use comments only when intent cannot be made obvious through code itself.
• Delete outdated comments ruthlessly — wrong documentation is worse than none.
• Keep both comments and docstrings short, direct, and honest.
• Use tools (like pydoc, javadoc, or IDE tooltips) to preview how your documentation looks to users.

In One Sentence

Docstrings tell others how to use your work.
Comments tell your future self why you built it that way.

Write both sparingly, truthfully, and in the service of clarity — the ultimate goal of clean code.