Click here to Skip to main content
15,867,568 members

Survey Results

Do you comment your code?

Survey period: 5 May 2014 to 12 May 2014

A repeat of our survey from 4 years ago. Let's see how things have changed.

OptionVotes% 
I add comment headers for all public classes, objects and methods, events, fields etc56740.04
I add comment headers for all non-public classes, objects and methods, as well as non-obvious logic inside these37226.27
I provide comments at the top of files29921.12
I comment any code that may be obscure (the "what") to a reader88162.22
I comment any code where the purpose (the "why") may be obscure93966.31
I comment on expected inputs, outputs and other results27719.56
I comment on exceptions, side effects or error codes31222.03
I comment on structures (loop endings, function endings etc)16911.94
I comment as a last resort when I can't make my code any clearer36325.64
I do not comment code.896.29
Respondents were allowed to choose more than one answer; totals may not add up to 100%



 
GeneralRe: Captain obvious comments Pin
Nemanja Trifunovic5-May-14 8:35
Nemanja Trifunovic5-May-14 8:35 
GeneralRe: Captain obvious comments Pin
Dennis_E6-May-14 21:58
professionalDennis_E6-May-14 21:58 
GeneralRe: Captain obvious comments Pin
aboubkr907-May-14 17:41
professionalaboubkr907-May-14 17:41 
GeneralGive credit where due Pin
Member 90635564-May-14 23:52
Member 90635564-May-14 23:52 
General"Sometimes".... Pin
imagiro4-May-14 22:29
imagiro4-May-14 22:29 
GeneralDepends on who will use my code Pin
zaxthealien4-May-14 21:02
zaxthealien4-May-14 21:02 
GeneralLast resort... Pin
Sander Rossel4-May-14 21:02
professionalSander Rossel4-May-14 21:02 
GeneralClasses and methods when necessary, everything else shouldn't need any comments. Pin
AlexCode4-May-14 20:53
professionalAlexCode4-May-14 20:53 
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!
Generaladd one more option Pin
Marla Sukesh4-May-14 20:42
professional Marla Sukesh4-May-14 20:42 
GeneralI try... Pin
Jim Meadors4-May-14 19:16
Jim Meadors4-May-14 19:16 
GeneralRe: I try... and regret not succeeding Pin
Erik Rude5-May-14 22:41
Erik Rude5-May-14 22:41 
General"Why" is really important than "What"...! Pin
koolprasad20034-May-14 19:04
professionalkoolprasad20034-May-14 19:04 
GeneralRe: "Why" is really important than "What"...! Pin
Thanks78724-May-14 19:22
professionalThanks78724-May-14 19:22 
GeneralRe: "Why" is really important than "What"...! Pin
Maarten Kools4-May-14 23:07
professionalMaarten Kools4-May-14 23:07 
GeneralRe: "Why" is really important than "What"...! Pin
Nemanja Trifunovic5-May-14 2:28
Nemanja Trifunovic5-May-14 2:28 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.