Iris Classon
Iris Classon - In Love with Code

Stupid Question 50: When should I document? And what is the best way to do it?

[To celebrate my first year of programming I will ask a ‘stupid’ questions daily on my blog for a year, to make sure I learn at least 365 new things during my second year as a developer]

Documenting code

I know this is another one of the ‘It depends’, but as always I am curious about the on what.

Let’s share first: I don’t document at the moment and I haven’t been documenting. I’ve kept what I consider a nicely structured code, with good naming conventions and hoped that the code would speak for itself. But I know that it does depend on the project. Here is one personal experience I’ve had where documentation would have been nice:

First large project I was involved in had out-commented code ( :( :( :( ) and thank-you-for-stating-the-obvious comments (connectionstring comment: this is the connectionstring). The project also had some excel documents attached that described the economy system (just a part of the large system) and the different codes and how they worked, but no referral to the source code so it was a separate document. Here and there a few comments would clear things up, but it took quite a while to figure out what was happening in the code. It was poorly structured and had bad naming (x and y variables and switching between Swedish and English names, and ‘funny-names’). The project itself was very domain specific and we (two devs) lacked domain training, there was nobody available to explain the code as the owner of the product did not have any contact with the responsible developer(s).

Then and there, some sort of documentation would have been great, as we would have managed to get more things done and even refactor the code somewhat- or at least provided some guidance to the next developer.

I always wondered how do you best serve up a source code, and when do you document, and how do you do that the best?

Comments

Leave a comment below, or by email.
Pinal Dave
9/23/2012 5:15:31 AM
This is excellent blog post - loved every word of it. 
Iris Classon
9/23/2012 5:20:08 AM
Reply to: Pinal Dave
Thank you :D And I need an answer, this is one question I couldn't answer. Hope to get some great comments on this one!! 
Tomas McGuinness
9/23/2012 5:25:29 AM
A good rule of thumb is that code should be self describing where possible. Give methods names that describe what they do. If a method doesn't read well, think about refactoring it. Sometimes complicated loops or calculations will need comments to help a developer along. 

If you're doing something obscure for a reason, maybe state the reason. I tend to approach it from the position - if I had to fx this in 6 months, could I figure out what the code is doing :) 
Petr Šrámek
9/23/2012 5:45:09 AM
I am trying to write short summary above every new class/struct/enum/method after I create signature of it.

If I can't describe it in the one simple sentence I know I am doing it wrong. So, it helps me to organize my thoughts in my head and produce better code(I hope). Also other developers appreciate short description when they see the code for the first time and can understand to your thoughts easily or he can find you're doing it wrong. 

If needed I expand the summary when I think/know the class/struct/enum/method is done and I won't change its behavior.

So, my answer is: I document my code immediately with short description and expand it when I know I am done with some piece of functionality to fully describe its behavior. 
Niclas
9/24/2012 1:37:35 AM
Reply to: Petr Šrámek
Why do you need the description if it is so short?
Why not give the description in the class, method or property name?

I mean do you describe what an StorePersonCommand class does, or what the ConnectionString property stands for?

I find it quite irritating to read comments that I have already figured out by reading the method or property name.

I would like to rephrase Scott Hanselmans statement about "There are a finite number of keystrokes left in your hands before you die" to "There are a finite number of scrolling left in your hand before you die".

I think when it comes to documentation about algorithms, and other more architectural decisions it would be better to place them in some word documents with pictures and state diagrams. I think the code can tell the story well in 99% of the cases. 
Petr Šrámek
9/24/2012 4:11:26 AM
Reply to: Niclas
Before I answer your the questions I need to say: Always take into count that there will be developers whom won't understand code you wrote for whatever reason - he/she is unexperienced, has lack of knowledge or don't know common principles and patterns. And it doesn't matter if he/she is coding same library or just consuming it in different app/service. They are learning while coding and you shloud help them understand how to do it right.

Why do you need the description if it is so short?
I dont need to. I want to. It is thoughts automated tests. If description dont satisfy, it doesn't pass the test and I know I need to do it better. I dont have 30 years of experience, but I want to produce good code and this short description helps me consolidate my thoughts.

Why not give the description in the class, method or property name?
I am giving self-describing names to anything I wrote. I think I do :)

I mean do you describe what an StorePersonCommand class does, or what the ConnectionString property stands for? I understood to connection string property, but what exactly does StorePersonCommand? Is this command for Adding, Updating or both actions? I think this is the reason why you have to write short description. You know what it means but I didn't when I can't take a look at code or when I don't try it.

I find it quite irritating to read comments that I have already figured out by reading the method or property name.
If read again on my comment you'll find I didn't write anything about properties and this is because its really selfdescribing, but some methods aren't so clear. And you don't need to read it. Simply skip to signature.

I would like to rephrase Scott Hanselmans statement about “There are a finite number of keystrokes left in your hands before you die” to “There are a finite number of scrolling left in your hand before you die”.
There is finite time of wondering how it works before you die.

I think when it comes to documentation about algorithms, and other more architectural decisions it would be better to place them in some word documents with pictures and state diagrams. I think the code can tell the story well in 99% of the cases.
I really dislike when I am looking into code and I need to open some f***king document to take a look on some description. These types of document are good for users not for developers and usually its not exactly the same as reality. People often forget to update it.

Just my opinion and I can be wrong. Thanks for the reply. 
Niclas
9/24/2012 4:25:17 AM
Reply to: Petr Šrámek
I don't agree with some of your answers.

Always take into count that there will be developers whom won’t understand code you wrote for whatever reason – he/she is unexperienced, has lack of knowledge or don’t know common principles and patterns. And it doesn’t matter if he/she is coding same library or just consuming it in different app/service. They are learning while coding and you shloud help them understand how to do it right.

It is exaclty here you need some documentation in word documents, if a new developer needs to be introduced to a new project, there is a need for introduction, which principles is used, code conventions and so on.
You should not teach the programmer with code comments about which principle you use, do it in another form with a white board or something before you let the developers in. Most often there is no need for documentation but a quick introduction with a white board for more novice developers.

StorePersonCommand - okey I didn't tell the whole story, the class has methods Save and Update on it, or why not SaveOrUpdate =). I mean there is no need for comments here. 
James Curran
9/24/2012 7:25:13 AM
I've heard many people advocate the "Don't comment -- write self-describing code" theory, and while I do suggest writing self-describing code, it cannot replace proper comments.

By it's very nature, code can only tell you what the code DOES.
Comments tell you what the code IS SUPPOSED TO DO.

In the difference lie your bugs... 
Alexander Strebkov
9/24/2012 8:32:52 PM
Reply to: Tomas McGuinness
My rule is: "If you think about writing comment for code, refactor the code" 
Esko Luontola
9/28/2012 3:52:54 PM
Reply to: James Curran
"By it’s very nature, code can only tell you what the code DOES.
Comments tell you what the code IS SUPPOSED TO DO."

Comments tell what the code WAS supposed to do at the time when the comment was written, after which the code has probably went through many iterations.

Automated tests tell that what the code is supposed to do and WHAT it actually does. Code tells HOW it does it. Comments are best left for describing WHY it does it. And even then, a comment is the last option after trying to make the code so obvious that it doesn't need further explanations. "A comment is an apology." http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode

Chapter 4, "Comments", of Clean Code is a good read. 


Last modified on 2012-09-22

comments powered by Disqus