I wrote a bit of a monologue in an e-mail to some of the developers at work the other day about documenting code. I've never been a great fan of huge swathes of inline comments splitting up what's only 4 or 5 lines of self-explanatory code, so when the mantra of "code should be self documenting" came along, I didn't really have much of a reaction to it. But I've been thinking about that, and I came up with the following conclusion, which was the opening line of my e-mail:
When have you ever bought a professional product that didn't come with a manual?
By this, I'm not just talking software product, I'm inculding hi-fis, coffee makers, and so on. I'm still of the opinion that code within the body of a method should be self documenting. Personally, I probably write 1 line of comments for every 10-15 lines of code. And it's usually just a "section heading". However, there are occasions where we all have to write obtuse code; using logical bit-shifts in some CPU-cycle critical operation rather than do standard calculations, marshal some parameter differently because of a bug in a system being integrated with, and so on. Such things clearly need descriptions of why a choice has been made. This still only amounts to one single-line comment every few methods or so, but it means that self-documenting code is simply something to aim for that will never quite be achieved.
My real bug-bear has been with XML-documentation of code - the fact that developers seem to use the "code should be self documenting" mantra to protect them from having to document the public interfaces that others have to program against; which really isn't code-commenting at all. When was the last day working in Visual Studio .NET, you didn't make some use of MSDN? Whether it's Intellisense, hitting F1 on a method, or searching for a class in the MSDN Library? That documentation's all there because of XML comments. To me, putting a system into a live environment in a financial institution with no technical documentation for it is unprofessional - plain amateur, if you will. Yes, the code should be self documenting, but what about the purpose of each method? Details on where it's called from? The permissible values of parameters? Details on why something's changed from a previous version? What the code is specifically not supposed to support? How it deals with concurrency and locking issues?
This isn't about "commenting the code" - it's about when teams in an enterprise are moving between projects on a regular cycle, or when support is outsourced, or when your code is externally exposed for others to consume - it is aboslutely critical that documentation of this is produced in such circumstances. It just happens that one of the best tools for doing this, and allowing integration with other documentation/the development environment is NDoc. And it just happens that this works by having you insert the documentation into the code. Is this a coincidence? Not likely, if code and documentation are maintained separately, they will no doubt diverge, but having errors in the build process when doing continuous integration means there are no excuses for a system becoming unsupportable/opaque.
Thinking about it, it's in a developer's best interests, despite the extra time, effort, and clutter of the class (I really wish there was a neater way of handling this in .NET, such as a comment-behind file, as suggested). How many developers complain that they've become tied to a project, limiting their progression, all because of the entrenched knowledge of the intricacies, or the speed with which they can develop on it? When I ever get down to developing code nowadays, I now religiously document every class and public property/method, along with any non-obvious private members (i.e. ones that are hacked and I need reminding to come back to) - it's common courtesy both to myself and anyone else that ever comes across it.
Final thought: How long would it have taken you to learn .NET if none of the MSDN documentation had been present? What would the cost of that have been?