3 ms·
I recently talked with a colleague about documentation. We both studied math and were frustrated about the lack of documentation from our predecessors. I discus
by snowpid 2y ago
I recently talked with a colleague about documentation. We both studied math and were frustrated about the lack of documentation from our predecessors. I discussed with them very often the topic but both we resisted. One was claiming he writes "self documentated code" and the other one was smart but wrote none approachable code.
I guess the difference that (in Germany) math exercises cares more about reasoning and explaining while in CS / informatics solution is only the tested result. So yes, coder make the world more complicated ;)
- ncann 2y ago"self documentated code" is probably the biggest lie that the Clean Code gang has managed to indoctrinate generations of programmers who just don't know any better.
- JonChesterfield 2y agoGiven enough experiences of documentation diverging from reality - the system does not behave how the docs claimed it should - people lose faith in the documentation. That may explain the sentiment that the code is the documentation. There may be some html or pdf with "documentation" in the name, but if it's inaccurate, you're going to end up looking at the code anyway. If that's your experience it makes writing documentation hard to justify. It's a poor approximation to reality which becomes steadily less true over time. So really what's the point. We need something closer to live documentation which runs the examples against the codebase and fails CI when they stop working to have a chance. Some projects do that. Deriving docs from comments helps a little but comments are often wrong too.