Hacker News new | ask | show | jobs
by parasight 1596 days ago
Self-documenting code
2 comments

Not all code can be self-documenting, especially optimized algorithms and complex operations. Comments serve to add requisite context and clarification that code alone cannot provide. Simply regurgitating the obvious in comments is a waste.
yes, agreed. good document is about why, not what.
I do not believe this will work.

1. document should be about why, not what.

2. not all decisions can be revealed in code itself. (for example, adding a delay to workaround a hardware bug.)

3. the biggest part missing from code documentation is the big picture document, not really the code level document. even you know what a class/function is, you don't know how it is used in the entire project, its life cycle, etc.