Documentation style

Code should be easy to follow. This can be achieved in a number of ways:

1. appropriate and meaningful naming
2. commenting on especially difficult algorithms or complex code
3. 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.