|
I've made a habit of commenting my code thanks to CodeProject. Preparing a source code for an article to be published in CodeProject is not exactly same as developing an end-user application. Readers may read the entire code and tried to understand line by line so comments are mandatory. Based on the viewers questions and suggestions for previous articles, I could decide what exactly should comment in the code of next article.
|
|
|
|
|
If I am in a good mood, I will comment legacy code saying, //fixed joe 05052014.
Then if I have some very complicated business logic that was not documented well, I will try to comment a decent explanation of what is going on.
Otherwise, my naming conventions and KISS Principal should explain the code.
|
|
|
|
|
Then there's the commenting on the comments made on questions regarding code commenting.
Though, when asked if I commented on a comment when that comment made of which was commented on was a questionable comment, I give the standard reply:
"No Comment."
|
|
|
|
|
I initial and date my comments as a matter of habit... Many times has it saved me from the Spanish Inquisition!! (Look, the last time this function changed was 6/5/2008 - it can't have suddenly caused the problem you are referring to!!)
|
|
|
|
|
_Damian S_ wrote: it can't have suddenly caused the problem you are referring to
You wouldn't believe how many times that has not been true for me. The problem is every piece of code relies on a certain set of assumptions. Over time, as operating systems or hardware changes, those assumptions may no longer be valid. Code that worked may stop working or break in subtle ways. Multi-threaded code is my favorite example. I've had code that worked correctly in a single CPU environment break when Hyperthreading was introduced, and then broke again in a multi-processor environment.
Software Zen: delete this;
|
|
|
|
|
Yeah, fair point... I work on fairly run of the mill business apps though, so I would have to be super-unlucky to be shafted like that... but it will come!!
|
|
|
|
|
That;s what source control and a 'blame' function is for!
|
|
|
|
|
I try to make all my code DoxyGen compliant.
Along with Antimatter and Dark Matter they've discovered the existence of Doesn't Matter which appears to have no effect on the universe whatsoever!
Rich Tennant 5th Wave
|
|
|
|
|
|
From Confessions of a bug addict[^] : I try to write the comments when I am assembling the code fresh from a good night's sleep that I will be thankful for when debugging that same code at 03:30am when something has blown up.
|
|
|
|
|
Please see pet peeve #1 in this[^] article.
/ravi
|
|
|
|
|
I remember 
|
|
|
|
|
How about the...
I try to write code that will comment itself??
or
I only comment code when the code itself isn't already self documenting.
|
|
|
|
|
I go for a minimalist approach. Too much comments just get in the way and make the code harder to read and I really hate "captain obvious" comments:
float GetSpeed() const
void SetEditMode(int editMode)
|
|
|
|
|
The code base I am using has comments like this:
con.Open();
I remove them whenever I come across them. 
There are only 10 types of people in the world, those who understand binary and those who don't.
|
|
|
|
|
Really makes you question the reasoning ability of the coder when you see statements like that.
|
|
|
|
|
You forgot to explain what "con" is in your comment 
My plan is to live forever ... so far so good
|
|
|
|
|
Commenting for the sake of commenting... not that there is any value
|
|
|
|
|
More minimalist
float GetSpeed() const
void SetEditMode(int editMode)
But I prefer the below one because the first two method names are good enough to understand the purpose. See the 3rd method
float GetSpeed() const
void SetEditMode(int editMode)
void MeaninglessMethodNameBySomeone(int editMode)
|
|
|
|
|
My personal favorite:
i++;
|
|
|
|
|
God, I hate those. That's worse than not commenting when it is needed.
|
|
|
|
|
|
My commenting (on the top) is often to give recognition that I wrote a program of sorts, as a disclaimer for everyone to see. Taught it in college, so I'm not letting that bit of knowledge go.
Otherwise, my commenting is mainly single-line statements telling "What" or "why" something is added when it isn't clear.
Obvious things shouldn't be commented, and that's the bottom line for me.
if (Broken)
then fix.this
else !fix.this
end-if
|
|
|
|
|
I do all this (and I guess I'm not alone) sometimes. Sometimes more, sometimes less. But since I (and again I guess I'm not alone) ran into the trouble of not understanding my own code when reading it later, let alone the code of colleagues, I tend to lift "sometimes" to "(nearly) always" - for nearly all most of the above cases.
|
|
|
|
|
If it's only for myself, the comments are minimum.
If it's freebies, more comments.
If it's for my work, I write comments as clear as possible.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
