in

ASP.NET Weblogs

Extreme JS

JS Greenwood's WebLog on architecture, .NET, processes, and life...

Code should be self documenting, right?

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?

Published Aug 18 2004, 12:05 AM by jsgreenwood
Filed under: ,

Comments

 

petal said:

can I also add that I think this approach encourages a focus on secure code - if you include standard fields within your documentation (e.g. have I placed validation checks on this input) it's a lot easier to find instances of potential vulnerabilities. Depending how you document, a security analysis can be made much easier. As I find the code behind model works well for me, maybe another change to the VS IDE would be to have a 'comment behind' file...
August 17, 2004 7:25 PM
 

diggit said:

"When have you ever bought a professional product that didn't come with a manual?"
We smalltalkers do it all the time. So what?
August 18, 2004 3:41 AM
 

Rob Styles said:

"When have you ever bought a professional product that didn't come with a manual?"
All the time, I rarely crack open the manual even if there is one and I know I'm not alone in that. If I have to hit F1 in VS.Net to find out what a method does then that is very much a failing on the part of the class designer.

"along with any non-obvious private members" - Surely it would be better to rename the variable or re-factor the code in order that the private _is_ obvious? While the common response to this is that it is not always possible; in my, albeit limited, experience this is not true.

I also think you're confusing two different things. The primary focus of documenting using inline xml documentation is not to document the code, it's to document the binary. You don't have the source for the .Net framework, so they provide the doc. For code you write of course it should be documented, but appropriate to the binary. For example, comments (which are about documenting the source) should describe why you're using seventeen bit shifts and masks instead of a more obvious algorithm, but you should not include that in the xml documentation because it's irrelevant at the point of using the binary.

The other thing to bear in mind is that the source is still _always_ the ultimate doc. That's why Lutz Rhoeder's .Net Reflector is _sooooo_ useful. The documentation tells you what code should do, the code tells you what it does do.

Hope you're having a good time up in sunny Derby.

Rob Styles
August 18, 2004 4:47 AM
 

JS Greenwood said:

OK, by "professional product", I meant VCR, lawn strimmer, etc... I wasn't talking just about software (and I'll update it to make that clear). And yeah, the manual ends up in the bottom of the box unread, but that's not the point - it's there in case I need it. Like at the weekend - I'd never looked at a car manual in my life before, but I suddenly needed to know the factory recommended geometry settings for the steering (don't ask!), and the thought of hacking the car apart to read tiny inscriptions on the sides of components didn't really appeal.

I agree that XML documentation is for the binary, not the source... and that's the point I was trying to make. People seem to use the mantra "code should be self documenting" as a shield to protect them from having to document the binaries. Like I said, I agree that the source should be 95-99% self-documenting, with comments only covering those hacky little bit-shifts. But, in a service oriented world where there could be many, many more people consuming the functionality that you expose than you realise, providing them with documentation on how to do that is essential - I should hope that the source WON'T be freely available to them. :) Again, I'll update the wording a bit to make that point clear.

> along with any non-obvious private members" -
> Surely it would be better to rename the variable
> or re-factor the code in order that the private _is_
> obvious? While the common response to this is that
> it is not always possible; in my, albeit limited,
> experience this is not true.

Agree with you completely on this. Have updated the entry to explain what I meant a bit more clearly - I basically use documentation on these methods to state that they're likely to change, as they are so obtuse.

On the subject of Reflector, I'd recommend giving Remotesoft's Salamander a go if you can get hold of it (it's commercial, and pricy)... it's by far the best .NET decompiler I've found.

Never known it rain anywhere as much or as randomly as in Derby. :(
August 18, 2004 7:24 AM
 

Jonathan Cogley said:

I disagree.

Xml documentation comments are like hairspray!
http://weblogs.asp.net/jcogley/archive/2004/02/14/72957.aspx

If you subscribe to Test Driven Development then XML comments have much less worth. I think the resurgence of self documenting code that you mention also has its roots in the popularity that Refactoring (with its formal methods) has been getting. Refactoring is an integral part of TDD and in many ways TDD makes it possible - how can you refactor code if you can't prove that it works afterwards?

My above post makes the argument against XML comments in the same manner that the refactoring camp makes their argument against code comments (CodeDeodorant as they call it).

One other thing, you mention using a one liner comment to label a section. This is probably a prime candidate for the "Extract Method" refactoring - rather move the code to a method with a really descriptive name and just call the method.
August 18, 2004 10:00 AM
 

JS Greenwood said:

Jonathan, from your own weblog:
"If your customer agrees that a documented API brings business value or your API will be published to developers without a source code release, then by all means generate documentation."

And in one of my own comments on the entry:
"In a service oriented world where there could be many, many more people consuming the functionality that you expose than you realise, providing them with documentation on how to do that is essential - I should hope that the source WON'T be freely available to them."

I totally subscribe to TDD, but I can't accept that it devalues documenting what's been done. There's a big difference between the development of code (high skill work), maintenance of code (low skill work), and consumption of the code by external (unmanaged) parties (unknown work). I don't think that providing a full set of NUnit tests for the .NET Framework would be a valid replacement for MSDN. Sure, it'd be great to have, but how would you ever find the method or class you needed... you'd need documentation!

Another example:
Code reuse has been something that's troubled me for a while - I've been very much against big up-front class libraries of supposedly useful business functionality, because it generally never gets used. I've come to the conclusion that this is because it's too hard to find the right class/method/know how it's supposed to be used, etc. Yet I don't find myself reimplementing the .NET Framework at every chance. Why is this? Because it's easy for me to find what I want through MSDN. The only thing they're lacking is decent real-world example usages (in the way all the old Borland Turbo C, etc. had)... this is where having the source for a test suite would be useful.

As for extract method refactoring, yeah - in some circumstances, but methods are like paragraphs - there's a length that feels "about right", and sometimes things shouldn't be split up as they shouldn't be called independently, etc.
August 18, 2004 10:18 AM
 

Jonathan Cogley said:

As you point out, there are definitely exceptions where documentation is very useful. I think the majority of people are still in the documentation is good camp (conventional wisdom, right?) and seldom question its real value. On our current project, writing XML comments (and maintaining them, arrrgh!) would only drain time away from features that could otherwise be implemented - and any developer using the code would always refer to the tests anyway.

I think the key is to decide what brings value to the project and not just assume that comments == good.

(BTW - good discussion!)
August 18, 2004 10:48 AM
 

JS Greenwood said:

>I think the key is to decide what brings value to the project and not just assume that comments == good.

Absolutely. The only reason techies exist is to add black ink to the bottom line. Anything that alters that shade to something approaching red's unacceptable (ignore the short-termism vs. long-termism arguments)

> On our current project, writing XML comments (and maintaining them, arrrgh!) would only drain time away from features that could otherwise be implemented

I know it's not quite the same thing, but that's is reminiscent of the projects where you hear the developers cry "we didn't have time to write tests, we were too busy implementing functionality". Has the value of those features been calculated vs. the long term maintenance cost that may be incurred? If it's purely an internal project with a fairly static development team, it's probably a no-brainer.

One of the "lightweight" documentation methods I was considering was embedding an "ID" to go with each method developed. As all of our methods relate to XP tests & tasks, we can tie them back to those via such IDs (the IDs of the tests/tasks), and in turn stories very easily. And as all of these stories are in an ASP.NET based system, it would be very easy to get "business purpose" documentation by linking the two together. If that makes sense. :)
August 18, 2004 11:09 AM

Leave a Comment

(required)  
(optional)
(required)  
Add
Terms of Use