A simple way to improve codebase quality

Can you write docs for the public APIs?

I vividy recall this feedback on my 2k-line PR with a deadline for reviewing. Over the years, it's a piece of advice that sticks as a surprisingly simple, but amazingly effective way to improve codebase quality.

Documenting public APIs compels you to reify and clarify your abstractions. The emphasis on public is important, as you are articulating your abstractions in a human-interpretable way. They are co-locating with your code, saving the trips to doc sites.

Considering the cost of writing and maintaining docs up to date might give you pause. But the time invested in writing would turn out to be trivial, compared to the time saved for fellow engineers on your team, or even yourself, staring blankly at the code and brain interpreting it, 20-level deep in a debugger stack, or frantically slack DMing. The values compound over time. Code is not a write-only medium. It's written for humans to read (and language models too). The more you write, the better you become at writing it.

What about maintenance? Don't you need to maintain the stale docs if they get out of date? Well, if you find the docs get stale frequently, it's usually a sign that you have the wrong abstractions. Think about refactoring the abstractions instead. It's easy to delete the doc if they can't keep themselves up to date. Being easy to delete is another sign that docs are good code. Docs are meta languages, but they are the types of meta languages that exist as code. They can be easily incorporated into code should you find the necessity.

In practice, docs could sometimes look like a verbatim of function signatures, which appears to contradict the conventional wisdom of "Comments should not duplicate the code". I've explained above how this wisdom doesn't apply to writing docs for public APIs, in terms of writing and maintaining the docs. The argument against visual clutter doesn't hold up since you can fold docs easily in modern IDEs. On the contrary, they give you additional context when you use the interfaces.