DEV Community

Discussion on: Don't Drown in Documentation

Collapse
 
mortoray profile image
edA‑qa mort‑ora‑y

I agree with this. Code documentation is best reserved for things that aren not self-explanatory in the code. They are also only a second resort, when refactoring doesn't fix the problem.

Documentation is however good for cross-module, or highly abstract, concerns in the code. Sometimes the flow of the code just doesn't capture the big picture. Comments on the big picture can help somebody new to the code. It tends not to get as outdated as quickly either, since the high-level concepts change at a slower pace.

As an expception, if the deliverable is a library, one would expect the API to be extensively documented. The users of the library shouldn't be expected to read the source to understand how to use the API.