Commenting your code...

      Do you work organized? Do you comment your code properly? Well... what does "properly" mean?

      Are there any official code commenting standards, something you just take over?

      I've been always using something quite plain and clear. My rules of thumb on commenting code are basically:
      1. Always comment the complexity! Be generous, it will always turn back on you if you don't.
      2. You don't have to comment all methods. It is obvious that the method doSomethingAndReturnAnInt(int intSomeIntVariable) will do something and return an int after using some integer variable. You don't have to just say it. Any comment has to add serious value.
      3. Always comment inner loops where you have too many. Of course you rather don't have such things for performance considerations, but when you do, make sure you know what are you looping through.
      4. Always use file header generous comments. Who modified what, when? Mark changes on "other people's file" with your name and date of the change and basic reason for changing it. Of course visual source safe does a similar thing but I can afford to have my reasons and still use this rule.
      5. Always comment external references. Web Services, external libraries, even references to other modules within your project. A 2nd developer looking at the code can find out everything by looking within same code. Specify what is that and why do you reference that, what are the parameters… etc.
      6. Always comment “flags” or defaults or conventions that lead to constants usage in the middle of the code. If you have code like if (x=193) {executeSomeCalculation(intSomeValue)} then you better specify what 193 is. Of course that if you have code like that something is wrong with you, but I rather know what was in your head at that moment then worrying about your development skills.
      7. Always comment when you feel like it. When you create something, when you are impassionate, tell the world about it. Document your creation. C’mon, I know you feel like that from time to time. Why do you code otherwise?
      8. Always use proper variable and methods naming. This will lead to less need of comments.
      9. Always add details for multi-layer applications where you are referencing sql stored procedure. It is very usefull to look in the code and see a method named getSomeDataFomBD(param) that has as comment something like /* will cal stored proc named returnSomeDataFromDB */. It definitelly helps for gebugging.

      There are more, but enough of that…

      But this is what the priest says not what the priest does :) It doesn’t mean I always do. I always try.

      From my experience, coding comments is a matter of corporate culture within software providers. They all start with the basic and adapt to their best practices. Most of them have quite good practices and methodology as reference, but very few apply it right.

      If there it is no rule enforced and no strict policies, including the validation after, then no one will do anything.

      There are various reasons for adding code comments:
> Because you are very organized and experienced
> Because you are working 12 hours a day on 5 projects and you will forget if you don't add comments
> Because you are working on other developer’s code and you want to make sure you "mark" down your place
> Because you need to impress customer tech representative
> Because you are not sure about what you are doing and you hope someone will eventually have a look at it
> Because you are going to be checked by your boss
> Because the client will check it randomly and you are always lucky
> Because you build custom software but you will probable reach in 4 years from now to maintain it.
> Because you are just thinking you are inventing something cool and the world has to know about it
> ...

      Depending on all these above, you might have more or less comments, more or less useful, more or less logic.

      There are basic rules that definitely have to be respected. I did not see good commented code too often. I saw "standard" code comments in most of the cases or no comments at all.

      I think that standard code comments can be easily removed by having very good and self explanatory variable naming or by having a general organized coding style. What is the need of describing each function name and parameters if you get it from the name. I would love to see code comments that mean something, that describe something interesting, something that will let me understand the complexity by reading it and not invite me to dig a lot in order to fully understand.

      I've seen those and they are showing up especially when you put passion on what you're doing, when you feel you invent that thing and you want to come back later or show it off or train someone, etc.

      Most of the development shops are actually trying and doing their best with it. As a customer you do not want to hear about it since it seems it will cost you more. You would love it done somehow in the background or, if you buy the final product, you just don’t want it done at all.

      As a provider, you add comments when you are going to maintain the thing for years or when you want to live out of the product. And, very important: you pray that the other providers DO add comments for the time you will end up maintaining other guy’s code.

      Here's a link that made me laugh a lot. It reflects many of the above by examples from real code comments. It worth reading and please focus especially on the comments on the article, not the article itself. They are hilarious!!!

      http://stackoverflow.com/questions/184618?sort=votes&page=1

Other references (please come back with more):

Some basic information here:
http://www.gnu.org/prep/standards/standards.html#Comments
http://www.cs.swan.ac.uk/~csbob/teaching/laramee07commentConvention.pdf
http://www.winnershtriangle.com/w/Articles.XMLCommentsInCSharp.asp

Wiki info:
http://en.wikipedia.org/wiki/Comment_(computer_programming)

ToDo or not ToDo
http://www.approxion.com/?p=39

.