Question

I have a colleague who insists that his code doesn’t need comments, it’s "self documenting."

I’ve reviewed his code, and while it’s clearer than code which I’ve seen others produce, I still disagree that self-documenting code is as complete and useful as well commented and documented code.

Help me understand his point of view.

• What is self documenting code
• Can it really replace well commented and documented code
• Are there situations where it’s better than well documented and commented code
• Are there examples where code cannot possibly be self-documenting without comments

Maybe it’s just my own limitations, but I don’t see how it can be a good practice.

This is not meant to be an argument – please don’t bring up reasons why well commented and documented code is high priority – there are many resources showing this, but they aren’t convincing to my peer. I believe I need to more fully understand his perspective to convince him otherwise. Start a new question if you must, but don’t argue here.

Also, those of you who are arguing against self documenting code -this is primarily to help me understand the perspective (ie, positive aspects) of self-documenting code evangelists.

Answer 1

In my opinion, any code should be self-documenting. In good, self-documented code, you don’t have to explain every single line because every identifier (variable, method, class) has a clear semantic name. Having more comments than necessary actually makes it harder (!) to read the code, so if your colleague

• writes documentation comments (Doxygen, JavaDoc, XML comments etc.) for every class, member, type and method AND
• clearly comments any parts of the code that are not self-documenting AND
• writes a comment for each block of code that explains the intent, or what the code does on a higher abstraction level (i.e. find all files larger than 10 MB instead of loop through all files in a directory, test if file size is larger than 10 MB, yield return if true)

his code and documentation is fine, in my opinion. Note that self-documented code does not mean that there should be no comments, but only that there should be no unnecessary comments. The thing is, however, that by reading the code (including comments and documentation comments) should yield an immediate understanding of what the code does and why. If the ‘self-documenting’ code takes longer to understand than commented code, it is not really self-documenting.