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

This is excellent blog post - loved every word of it. 

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!! 

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 :) 

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. 

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. 

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. 

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. 

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... 

My rule is: "If you think about writing comment for code, refactor the code" 

"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.