97 Things Every Java Programmer Should Know

Chapter 95. Write One-Sentence Documentation Comments

Peter Hilton

A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.

Kevlin Henney

You’re probably either writing too many comments in your code, or none at all. Too many generally means too many to maintain, which risk becoming dangerously inaccurate comments that you’re better off deleting. Too many is also likely to mean that they’re badly written and unimproved, because it’s hard to write “lucidly and clearly.” None at all means relying on perfect naming, code structure, and tests, which is even harder than it sounds.

We’ve all seen a lot of code whose authors didn’t write any comments at all, whether to save time, because they didn’t want to, or because they thought their code was self-documenting. Sometimes code really is that well written: the first thousand lines of a new project, the hobby project written in artisanal handcrafted code, and maybe the mature well-maintained library project whose narrow focus keeps the codebase small.

Large applications are different, especially enterprise business applications. Comments are a problem when you’re maintaining 100,000 lines of code that other people wrote and are still adding to. That code isn’t all going to be perfect, and needs some explanation. The hard question is how much explanation: ...