Documentation style

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 hea开发者_JS百科rd of a documentation style like this? Is it a good practice? Seems extremely overzealous to me.

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.

I would have said the opposite. A good documentation is a code that speaks for itself! Some comments have a tendency to make the code less readable and enjoyable. If we keep saying this to beginners, there is a huge risk that they will write programs where the code to comments ratio will be very very low (in other words, it certainly means that they have over commented their code which is not that good). A comment should be written only and only if it explains a non trivial algorithm or instruction. The rest should be left to the code (like naming your variables such as you understand their job).

In the context of a class, yes. That professor wants to know your intent behind the code. That professor has no easy way to ask this except to look at your code. It will also help you section off parts of your assignment into little programmable chunks.

In the real world? It depends. We log work to any classes we modify while committing-- it's a good place for us to document the intent behind changes. Lots of comments would require a lot of maintenance. If the comment explains the why of an implementation, and that implementation changes, that comment better change too.

I have, my own under-grad work initially had a requirement like that. It might be a bit overzealous, but if it gets people to comment their code then I'm all for it.

It is a good practice. It means that you can treat the code as black box, which makes life easier in general. I agree that documenting like this is, is not fun, but you may consider letting a colleague help you with it. Maybe even a specialist like a technical writer.

The instruction is vague. You should seek clarification from your instructor.

Some might interpret that instruction to mean your comments describe the code. That is not good practice after college. However -- and this is from experience -- to those grading beginners' work, it may be very helpful. You want to be helpful to those grading your work.

An alternate interpretation is that you should document the purpose of parts of your code -- classes, methods, blocks of code in long methods that might be better refactored into smaller methods. Examples of some of this can be found in generated API documentation in many class libraries.