How much documentation do we need and when should we write it?

Question

This question is inspired by the following sources:

• Clean code by Robert C. Martin
• Agile Principles, Patterns, and Practices in C# by Robert C. Martin and Micah Martin
• What is software design? by Jack W. Reeves
• My current project (where we should comment everything in the code)

Mr. Reeves states in his paper that the code is the design and the compiler is doing the atual build, that is, we, the developers, do the actual design when we coding. So do we need to write the design document before we start coding? Should we comment everything we write in code? I think not. Take the following simple example:

//<summary>
// True if object is deleted
//</summary>
public bool IsDeleted() {...}

Isn't the comment just noise? What do it add to the code that the function name doesn't already says? And how do we keep that documentation, and design documentation, up to date? When doing are test, debug and fix we will most likely change the code and design... but will we change the design document? Many of us will most likely forget to update the design document because it is not the real design document, the code is.

So how do we create good documentation? Write good code that conforms to the SOLID principles (if object oriented programming), and also write your code so you can read it, that is use proper names.

So what do you say? How much documentation do we need? When should we write it? How do we maintain it?

Answer 1

I usually write comments for myself in the time of coding and a whole documentation when the module is done (But immediately after it's done, so I don't forget anything).

What I mean by "commenting for myself"? I consider myself as a pretty average programmer, so I can't grasp difficult algorithms or regexes from first sight (usually neither from second nor the third :)

But I want to create the neat, easy-to-understand code. So I never comment anything that speaks for itself (it would be rubbish), but I always comment: a) every subroutine and b) every algorithm.

All I need is that I myself could understand the code after a year or so.

Answer 2

My bullet points for documenting:

• Document anything that is independent of the actual code but is necessary to use the system in an external document. E.g. authentication or signature specs, custom protocols and the like. Be as detailed as necessary, include examples.
• If the system is not based on some well-known structure, like an established framework, document a high-level overview of how stuff is supposed to work together in an external document. And I mean really high-level, the less detail the better. Half a page on how the files are organized or the rough steps a request cycle goes through, just something get a newbie started learning the system.
• Leave an introductory comment on what a class or module is supposed to do if it's not completely obvious. With a proper directory structure/naming/namespacing this should rarely be necessary.
• Leave a summary comment on what a function/method does if it's not obvious from the name or if the name may be ambiguous. Your example IsDeleted() function probably doesn't need a comment. A method named set() may need a comment.
• Add a full interface spec to a function/method if it takes arguments. This applies a lot more to weakly/dynamically-typed languages than to strongly-types ones though. Especially if the method takes option hashes or the like, document what options the hash may contain and what they do.
• Comment individual lines of code if it's not readily apparent what they're for while skimming the code. If you apply proper naming and try to KISS, you should rarely, if ever, have to do this.

This obviously depends on the purpose of the system though. Internal documentation is usually fine like this. If you're expecting people to use your library through interfaces though, these interfaces need complete documentation with usage examples.

Answer 3

This might be a bit philosophical, but I think the golden rule applies very well here: write as much code documentation as you prefer to find in a piece of someone else's code which you have to understand.

Answer 4

To expand on Nils answer - If you want to find a good level of documentation, just have another developer read your code. Document the things he ask what it is or why it is there. That's roughly as much as you need. After a few projects one usually gets a sense of where to document by doing this.

Edit: Note that one shouldn't use the same person too often, as he'll get used to your style. Nor should one, obviously, use someone actually working on the same project, as it'll be more obvious for him what things mean.