Comment by treis
5 years ago
>end up reading the source half the time, anyway; documentation is often incomplete, dated, and possibly incorrect.
I'm a pretty firm believer that documentation has to live next to the code. Otherwise it's nearly guaranteed to be out of date and/or incomplete
100%
Thoroughly commented code tends to end up a couple changes out of date. A separate file in the same directory ends up a couple major refactors out of date. A separate file in a separate system ends up a couple company-wide reorgs out of date.