March 13, 2015 at 12:11 pm
Ian Rennie (3/13/2015)
I remember seeing the comment "What has she done now?". Unfortunately, apart from the discourtesy, the author had not checked how his code rendered - it appeared in an email to tens of thousands of his organisation's customers
:w00t::hehe:
That is great. Not only a bad and slanderous (intended) comment, it came with a mass email campaign.
Jason...AKA CirqueDeSQLeil
_______________________________________________
I have given a name to my pain...MCM SQL Server, MVP
SQL RNNR
Posting Performance Based Questions - Gail Shaw[/url]
Learn Extended Events
March 13, 2015 at 12:20 pm
I have seen a couple of comments in this thread about the type of comment that states the obvious.
I don't necessarily take issue with a comment that states the obvious. What is obvious for one person, is not necessarily obvious for the next.
I have worked many times where a developer did not understand a code segment where the "obvious" statement like this one in the notes turned on the light bulb for that dev.
-- Deleting from RunLog table where StartDate is older than 3 months.
There have been plenty of other things where the code seems blatantly obvious to me but makes no sense to another person and the same is true vise versa. A simple comment stating the "obvious" makes it sometimes easier to fly through a code review and to double check the intent of the comment versus whether the code actually does that.
A prime example was for a client where the code was supposed to delete where startdate was older than 30 days. But the code said this
Delete from sometable
where startdate < 30
Suddenly the comment became extremely useful because it pointed out a quick bug immediately.
Jason...AKA CirqueDeSQLeil
_______________________________________________
I have given a name to my pain...MCM SQL Server, MVP
SQL RNNR
Posting Performance Based Questions - Gail Shaw[/url]
Learn Extended Events
March 13, 2015 at 12:49 pm
SQLRNNR (3/13/2015)
I have seen a couple of comments in this thread about the type of comment that states the obvious.I don't necessarily take issue with a comment that states the obvious. What is obvious for one person, is not necessarily obvious for the next.
I have worked many times where a developer did not understand a code segment where the "obvious" statement like this one in the notes turned on the light bulb for that dev.
-- Deleting from RunLog table where StartDate is older than 3 months.
There have been plenty of other things where the code seems blatantly obvious to me but makes no sense to another person and the same is true vise versa. A simple comment stating the "obvious" makes it sometimes easier to fly through a code review and to double check the intent of the comment versus whether the code actually does that.
A prime example was for a client where the code was supposed to delete where startdate was older than 30 days. But the code said this
Delete from sometable
where startdate < 30
Suddenly the comment became extremely useful because it pointed out a quick bug immediately.
My point earlier was that this form of comment is useless; it's basically just re-stating in engligh the functional operation of a single statement. But T-SQL is declarative and verbose enough that it doesn't need such comments intended to simply describe it's function.
-- Deleting from sometable where StartDate is older than 30 days.
However, this comment is better. It tells us when the change was coded, who made the change, and why we are deleting from the table in the first place.
-- 2014/02/13 J.S. TFS34621: Performance optimization. Operations requested that history older than 30 days be purged from run log table.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
March 13, 2015 at 12:59 pm
Eric M Russell (3/13/2015)
My point earlier was that this form of comment is useless; it's basically just re-stating in engligh the functional operation of a single statement. But T-SQL is declarative and verbose enough that it doesn't need such comments intended to simply describe it's function.-- Deleting from sometable where StartDate is older than 30 days.
However, this comment is better. It tells us when the change was coded, who made the change, and why we are deleting from the table in the first place.
-- 2014/02/13 J.S. TFS34621: Performance optimization. Operations requested that history older than 30 days be purged from run log table.
i tend to agree with Eric here. State the business reason, or logical reason, not what the code does.
March 13, 2015 at 1:05 pm
--place comments here
And no one ever did
March 13, 2015 at 1:30 pm
Digressing slightly, how would the threadizens describe the optimal code comments? Obviously the opposite of that would be the worst;-)
😎
March 13, 2015 at 1:48 pm
Microsoft Team Foundation Server has a feature in it's source control where you can compare one version of a source file to another past version, and it will highlight all code blocks and lines that were changed in the interim checkins, and each highlight includes the work ticket # and comments entered for each checkin. So thos will sort of automatically comment the code visually, assuming the developers perform regular checkins.
"Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho
March 13, 2015 at 1:56 pm
We had one developer who was notorious for his comments, which was saying something considering the 'quality' of the code it decorated. The problem wasn't necessarily the comments themselves, it was the noise. You'd have a method like this:
//The Add method adds numbers
public int32 Add (int32 a, int32 b)
{ //Start of the method
int32 result; //This is the result variable
result = a + b; //Adding a + b together
return result; //This is where the result is returned
} //End of the method
Starting at the top, no one apparently showed him /// so at least it might help another dev calling his method. But nearly EVERY line has a comment, but most did nothing more than re-state the line of code in English. If you did stumble along a line where you'd want an explanation as to why the code did what it was doing, you might have "if (inputValue == 32) //Check to see if the input is 32..." but no explanation as to WHY 32 was important. It was very difficult to separate the wheat from the chaff, as it was mostly chaff.
Speaking of 32, typically there were only two variable types this developer would declare: int32 and ArrayList. No idea why.
March 13, 2015 at 2:03 pm
My all time favorite in several places:
// I told Cxxxx XXXX (actual name was here) this doesn't work the way he wanted it to because his equations are wrong but I coded it the way he insisted even though it was wrong.
Finally, followed up with one dated about 3 months before I came on board:
// if you're reading this comment, you by now realize I quit because Cxxxx XXXX is a #$A#$AEing idiot!
:w00t: Incredibly, the programmer was right - the boss wanted stuff coded his way because he thought his math was superior to everyone else. LOL
March 13, 2015 at 3:22 pm
I'm guilty of a number of bad comments in my code. Some of my favorites are (all paraphrased):
Per {executive}, doing it this way.
This is a really bad idea but I'm following orders.
Hopefully we fix this later.
and my favorite:
What was I on when I wrote this? Oh that's right, Lortab. No idea what this is supposed to do.
To this day I still get messages from people who have followed my place maintaining apps I developed from scratch or was primary on long, long ago. "I LOVE YOUR COMMENTS. The developers can't figure out {X} but they're hilarious."
I present my old self as an example of what not to do. 😀
March 13, 2015 at 3:39 pm
markjholmes (3/13/2015)
I'm guilty of a number of bad comments in my code. ... I present my old self as an example of what not to do. 😀
"No one is a complete loss: they can at least be used as a bad example." :hehe:
-----
[font="Arial"]Knowledge is of two kinds. We know a subject ourselves or we know where we can find information upon it. --Samuel Johnson[/font]
March 13, 2015 at 4:11 pm
Eric M Russell (3/13/2015)
Microsoft Team Foundation Server has a feature in it's source control where you can compare one version of a source file to another past version, and it will highlight all code blocks and lines that were changed in the interim checkins, and each highlight includes the work ticket # and comments entered for each checkin. So thos will sort of automatically comment the code visually, assuming the developers perform regular checkins.
TFS takes what most Source Control Systems do and pushes it a little bit further. I have to say that the above highlights some of the improvements that add real engineering value to the development process.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
March 13, 2015 at 5:08 pm
One of my favorite comments after I suggested a fellow developer comment his code put in
// Begin if
{
.. Code
}
// end if
I am not kidding
March 13, 2015 at 5:55 pm
markjholmes (3/13/2015)
I'm guilty of a number of bad comments in my code. Some of my favorites are (all paraphrased):Per {executive}, doing it this way.
This is a really bad idea but I'm following orders.
Hopefully we fix this later.
and my favorite:
What was I on when I wrote this? Oh that's right, Lortab. No idea what this is supposed to do.
To this day I still get messages from people who have followed my place maintaining apps I developed from scratch or was primary on long, long ago. "I LOVE YOUR COMMENTS. The developers can't figure out {X} but they're hilarious."
I present my old self as an example of what not to do. 😀
I actually think that is not so bad - if I was reading the code, at least I would know why it stunk and would not have to waste time trying to find a good reason why it was written that way.
I hate spending time trying to figure out if the code I think is bad, actually is - if you tell me it's bad and I think it's bad, at least I know it is bad.
MM
select geometry::STGeomFromWKB(0x0106000000020000000103000000010000000B0000001000000000000840000000000000003DD8CCCCCCCCCC0840000000000000003DD8CCCCCCCCCC08408014AE47E17AFC3F040000000000104000CDCCCCCCCCEC3F9C999999999913408014AE47E17AFC3F9C99999999991340000000000000003D0000000000001440000000000000003D000000000000144000000000000000400400000000001040000000000000F03F100000000000084000000000000000401000000000000840000000000000003D0103000000010000000B000000000000000000143D000000000000003D009E99999999B93F000000000000003D009E99999999B93F8014AE47E17AFC3F400000000000F03F00CDCCCCCCCCEC3FA06666666666FE3F8014AE47E17AFC3FA06666666666FE3F000000000000003D1800000000000040000000000000003D18000000000000400000000000000040400000000000F03F000000000000F03F000000000000143D0000000000000040000000000000143D000000000000003D, 0);March 13, 2015 at 7:41 pm
Two year old comments in app that still didn't work correctly........"Sprayed perfume on this dookie to try and make it work."
Viewing 15 posts - 61 through 75 (of 156 total)
You must be logged in to reply to this topic. Login to reply