Code should be easy to follow. This can be achieved in a number of ways:
- appropriate and meaningful naming
- commenting on especially difficult algorithms or complex code
- extensive documentation of all the code
Appropriate documentation will use all three approaches where they are appropriate.
However, when the audience for the code is primarily trying to understand the code and assess understanding of the concepts - ie in an academic context, the third one is likely to be highly desirable.
All code should be written and documented so that it can be understood by your worst detractor, when he is on callout at three o'clock in the morning because there is a problem with the production system.
At the same time, excessive comments are another item to be maintained, and kept in sync with the code when changes are made to the code, and comments are the least likely item to be properly maintained under change.
manpreet![Tuteehub forum best answer]()
Best Answer
2 years ago
From the syllabus for one of my programming classes: "Your documentation will be sufficient if it would be possible to read only the comments, without looking at the code, and explain what the code does."
Have any of you heard of a documentation style like this? Is it a good practice? Seems extremely overzealous to me.