4 ms·
A big issue with documenting what the code does is that the code and documentation can very quickly fall out of sync. As this posts says, it's much more useful
by ChrisSD 6y ago
A big issue with documenting what the code does is that the code and documentation can very quickly fall out of sync. As this posts says, it's much more useful to document the intent of the code, or why there's this mess of seemingly hacky code (see issues #80681, #82108, #66065).
Also be wary of unit tests that are overly tied to the specifics of an implementation. These can be worse than useless when it comes to changing code. I.e. asking "why are my tests failing?" and finding out it's only because I breathed near the code.
- mrkeen 6y agoSystem tests too! The last code-base I worked on had do-everything system tests (with unexpectedly good coverage, I'll admit). They were so slow and passed often enough that I didn't immediately spot flakiness. I got suspicious when the tests started failing regularly when I added new unrelated code.
- otterley 6y agoA good way of avoiding this trap is to require updated comments as a condition of merging a pull request.