|
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.
|
|
|
|
|
More often than not have I seen code that is unclear, outdated or just wrong.
It seems people are unable to write correct and consise comments and update it when needed.
People seem to forget that a comment is just a line of code that needs to be maintained, just like the rest of your code.
Some examples of what I've seen:
int helper;
customer.Save();
int i;
int i = 42;
int j = 42;
int x = i + j; With so much noise I'd rather not see any comments at all. You'll probably still be able to figure out what code does anyway, it just might take a little longer.
Writing comments isn't fun. Most programmers I know take time to write comments, but don't take time to do it well. No one take time to update comments when they update code.
To me it's a last resort. When I write a bit of code that I really can't make any clearer than what it is I might write a comment. If a comment could make it any clearer that is.
It's an OO world.
public class SanderRossel : Lazy<Person>
{
public void DoWork()
{
throw new NotSupportedException();
}
}
|
|
|
|