Comment by dehrmann
5 years ago
I end up reading the source half the time, anyway; documentation is often incomplete, dated, and possibly incorrect. For code, I'd prefer the time go into designing a cleaner interface and making what calls do obvious.
That said, I find high-level documentation for larger systems to be very valuable. I also find Python's docs to be lacking compared to Java's; I'm often left wondering about the definition of what type is returned, exactly what parameters should be, and which exceptions are raised. Java's docs are very explicit about all these things.
>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.
I agree. I'd like my documents to contain overview, intent, and exceptions. The actual implementation I can look up in the code. Also generated stuff is appreciated, like Swagger.
You should be reading the source all of the time. The point of documentation is to tell you what the code doesn't. If it tells you the same, you should delete the documentation.