3 ms·
I love comments at the beginning of files that explain what this component is intended to do and how it fits in the big picture. Documentation seems to be so m
by jdsully 8y ago
I love comments at the beginning of files that explain what this component is intended to do and how it fits in the big picture. Documentation seems to be so micro focused that its very hard to understand how a piece of code was intended to be used.
The Doxygen trend of just dumping APIs and comments at the start of functions and calling it documentation is horrendous.
- grogers 8y agoFor documentation meant to be consumed by others, sure. But for an internal module, these are exactly the types of comments that get out of date the quickest, since they are disconnected from the code they don't stay up to date as the code evolves.
- jdsully 8y agoGenerally speaking the purpose of an entire class rarely changes to be something completely different. In such cases new classes are made instead.