Survey Results - Do you comment your code?

I already said this in a poll a couple of weeks ago.

Code is like English, it's a piece of text that can be read.
The trick is to reduce the amount of code per method to the minimum and give meaningful names to all classes, methods and variables.
Comment your classes to describe the overall intention of that class. If you find multiple intentions maybe you should do some refactoring.
Comment your methods when the arguments or result require some complex logic. Still try to give meaningful names.

Reduce indentation inside methods to a maximum of 3, more than that only in specific cases, otherwise refactor your code. Small pieces of code are easier to read and more importantly, they are testable.

All these are good rules but documentation is fundamental.
Every time you push something to your source control, make sure you comment properly what you are pushing and why. Don't save any characters here. someone might see the changes history in a couple of months and it will be clear why the code changes from A to B. This is more important that why the code now is B.
Even more important, you'll be able to see not only the changes on this file but also which other filer were also changed... and why!

Also, having a proper issue project management/tracking tool is fundamental. All pushes should be linked to a task in the issue tracker.
Some source control tools support integration with issue trackers, otherwise just include the task/issue code in your push description text.
This way you can see the code, look for the history, read the author comments and if you need to have more details, read the task/issue that originated these changes.

This is all pretty fast to do. From code to the task you arrive in 20 seconds max.
Most of the time, if the code is well written, you'll have everything there, otherwise most of the times only reading the author push comments is enough.

So, again. No big in-line comments for me.

Here's a resume of what I said above:
- comment classes
- comment methods when really necessary
- use a task/issue tracking tool.
--> explain in detail what each ticket is about.
- use a source control tool
--> explain in detail what each push is about
--> keep a push per functionality, don't mix things in the same push

Cheers!

If you do commting, does i really help others or you do i just to follow process Smile | :)

SukeshMarla
www.sukesh-Marla.com
For technical trainings on MVC,WCF,Design Patterns,UML,WPF,BI,TFS contact SukeshMarla@Gmail.com or visit www.sukesh-Marla.com

...to comment my code so I can come back at any time in the future and pick it up again. I try. Roll eyes | :rolleyes:

<sig notetoself="think of a better signature">
<first>Jim</first> <last>Meadors</last>
</sig>

This goes for me. I try to do all - except for not commenting. Sometimes life gets in the way. And quite often I regret not doing better comments a few weeks/months/years down the line.

I comment any code where the purpose (the "why") may be obscure.
I think each code reader should know about the requirement of the development, in short, he/she should aware of 'WHAT'(is the requirement) , but we should comment for 'WHY'(we code this), cause reader should know 'WHY' I code this line.

(But I doubt how many times, we read comment before going through code )

Rating always..... WELCOME

The only reason people get lost in thought is because it's unfamiliar territory.

Code is what computers understand and comment is what human can understand. Requirement and coding are some thing different. We can not identify code on the basis of requirement. Comment is meant to quickly explain your code [And to reduce 15mins into 15secs.. Smile | :)

]

"When you don't know what you're doing it's best to do it quickly"- SoMad

The problem I have with commenting the "what" is that when making changes, you should also update the comments. If that fails to happen for whatever reason, the "what" comment is no longer explains the actual code. You're only going to find out when reviewing both the code and comment.

Rohan Leuva wrote:
Code is what computers understand and comment is what human can understand

*Machine* code is what computers understand. High level programming languages are designed for people.

utf8-cpp

Option	Votes	%
I add comment headers for all public classes, objects and methods, events, fields etc	567	40.04
I add comment headers for all non-public classes, objects and methods, as well as non-obvious logic inside these	372	26.27
I provide comments at the top of files	299	21.12
I comment any code that may be obscure (the "what") to a reader	881	62.22
I comment any code where the purpose (the "why") may be obscure	939	66.31
I comment on expected inputs, outputs and other results	277	19.56
I comment on exceptions, side effects or error codes	312	22.03
I comment on structures (loop endings, function endings etc)	169	11.94
I comment as a last resort when I can't make my code any clearer	363	25.64
I do not comment code.	89	6.29
Responses	1,416
Respondents were allowed to choose more than one answer; totals may not add up to 100%