My thoughts on documenting your code

A recurring topic in every project I’ve been involved with is when and where you should use XML comments and/or annotate classes and members with proper documentation. I’ve always been very specific about this, but in real live I meet a lot of developers who don’t seem to care about this, or worse, they reject the entire concept. Some of these people claim that the only real documentation is the code itself. And although I fully agree that a well-factored and properly named class is a crucial element in achieving a maintainable code base, proper documentation is just as important.

In my opinion, these three kinds of documentation are required for every professional code base.

• Class-level and member-level documentation helps you understand what behavior to expect without having to jump into the actual implementation details. It should also explain the responsibilities and the roles the class plays in the overall design, or the member within the class. This kind of documentation is not a replacement for proper naming. Both are crucial, and one should reinforce the other. So always document the expected behavior of all your public and protected members. But, don’t add documentation that repeats the name of the member. I’d rather have no documentation at all than that kind of useless crap.
• Inline comments, which you should use scarcely, are there to help you understand the thought process the original developer went through, to point you in the right direction, or to emphasize a particular…