|
Read several articles this year about the pros/cons of commenting your code. I've been up since 0400 working on code. With no comments.. or very limited comments. I'm not talking about what the code is doing, but I sure as hell would like to know why....
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
If the code is written with some disciplined architecture and perhaps sticks to the single responsibility principle, then a lot of commenting may not be needed. Still, even the best code only shows only what is being done, but not the intention behind it.
At work I have a real big uncommented mess of dozens of data tables, stored procedures with (half of) the application logic and on each data table at least seven or more triggers to do the second half of the application logic. The stored procedures and triggers are usually a few thousand lines long, try to do everything at once in the good old spaghetti style and are, of course, not commented in any useful way. Absolutely undebuggable and unmaintainable. How I would like to shake the idiot's neck who came up with this, but he is, as always, long gone and creates another such mess elswhere.
The language is JavaScript. that of Mordor, which I will not utter here
This is Javascript. If you put big wheels and a racing stripe on a golf cart, it's still a f***ing golf cart.
"I don't know, extraterrestrial?"
"You mean like from space?"
"No, from Canada."
If software development were a circus, we would all be the clowns.
|
|
|
|
|
Comments should enhance your code: I use XML commenting (to pass to intellisense) and a small amount of relevant commenting when things get complicated. But generally, most of my methods don't get a comment in the code - I keep them small so that it's pretty much unnecessary as they are self documenting.
What bugs me is:
A) Irrelevant comments: particularly those that repeat what the code is doing rather than explaining why it's doing it.
B) Wrong comments. Hate them. If you change the damn code, change the damn comments you lazy SOB! 
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
Griff - I agree, keep the comments current. As far as relevancy, I find myself guilty from time to time of this error. Good comments are like code, they must be maintained. Maintaining irrelevant comments is silly.
I'm mainly griping about high level comments, the crap that explains a particular process and why it's arranged in this fashion. I've been working on this product for 2 years, plus a previous one, so I know WHY things are done this way. But if we ever get hit by a truck, customer is in trouble.
Gripe #2 - not using complete names... FileNm for FileName? really?
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
I'd agree - but that's what the <remarks> section of the XML comments is there for!
I'm guilty of using "short names" for very temporary local variables:
frmInputBox ib = new frmInputBox("Please enter the user name");
if (ib.ShowDialog() == DialogResult.OK)
{
string userName = ib.Value;
...
}And such like.
But avoid "txtspk" variable names the rest of the time!
And while we're on the subject of names...I hate it when people use VS default names for controls...5 seconds extra for you to call it "tbUserName" instead of "textBox14", and hours of me swapping to design view to get a clue what holds what...
Bad command or file name. Bad, bad command! Sit! Stay! Staaaay...
|
|
|
|
|
OriginalGriff wrote: .I hate it when people use VS default names for controls...5 seconds extra for you to call it "tbUserName" instead of "textBox14"
What a relief - I thought I was some sort of wacko (nutter, across the water) that wanted the name of the control to tell me what it does: and then enjoying how it passes on the events and stuff automatically.
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "As far as we know, our computer has never had an undetected error." - Weisert | | "If you are searching for perfection in others, then you seek disappointment. If you are seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
OriginalGriff wrote: I hate it when people use VS default names for controls...5 seconds extra for you to call it "tbUserName" instead of "textBox14", and hours of me swapping to design view to get a clue what holds what...
Programmers who use VS default names should be defenestrated
If you have an important point to make, don't try to be subtle or clever. Use a pile driver. Hit the point once. Then come back and hit it again. Then hit it a third time - a tremendous whack.
--Winston Churchill
|
|
|
|
|
I had to go look that up... I have a new word in my vocab now.
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
I failed code review on a function that was incorrectly named. it was initialisetimer or some such, and it didn't, it actually enabled a system feature.
I bitched, the dev refused to change it saying its late, and he is tired, and then pushed it through to complete, even though my review was open!
REALLY pisses me off!
|
|
|
|
|
We (our Team) have deceided to apply the XCode comment style for our iOS-code. It provides some tooltip and assistent help.
I learned commenting gets important if different people work with the code.
Press F1 for help or google it.
Greetings from Germany
|
|
|
|
|
I try to use a three-tiered commentary when possible.
There's commentary through the code explaining what something does (that is trivial) and why it does it (particularly if one would not normally do it the way it's being done). Modifications to the original "working" code will also include a date in the comment.
There's a boiler plate on every method I create (or modify if VS creates it) and it will have the creation date stuff and then updates, bugfixes, etc., also with a date for the changes block.
Finally, a separate file (text) which keeps a bit of a narrative in blocks This will of course have a date and, if a version number change is made, it's up there, too. This isn't generally detailed, but will 'name names'.
The last of these is interestingly useful in that the chronology is all in one place and if things go wrong you can go back to see what you did then (and how to blame someone else).
All of these point to the same bottom line: I presume I'll have forgotten all about whatever it is I had done or was thinking if I ever need to go back there. The first person I ask for help is me . . . and comments are the only way I can answer.
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "As far as we know, our computer has never had an undetected error." - Weisert | | "If you are searching for perfection in others, then you seek disappointment. If you are seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
In our team we do not comment the code itself, but add an opening block of comments (where it appropriate) to explain how this code connected to the flow of the application and what the purpose of it...The reason is that we can nor afford single-responsibility and even one is responsible for a certain part of the code it is common that in absence of one someone else will pick up a bug-fix/feature request...
So comments that explain the purpose of some code (without getting in the implementation details) can be very useful...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
The code is there to meet requirements, so you can just add this all over:
|
|
|
|
|
charlieg wrote: but I sure as hell would like to know why....
Yeah, various voices have made noises about comments being unnecessary, not realizing that even well structured code will tell you the what and how but rarely the why.
Marc
|
|
|
|
|
The question is if the "why" should be documented in the code itself.
My opinion is that code should have as few comments as possible.
Good code describes itself (mostly) and bad code probably has bad comments too.
In my experience comments are never good.
Even written a tip about it (with some sad real world examples) 
|
|
|
|
|
Umm, I disagree. Or maybe I want to disagree. Perhaps a programmer's guide of the system (separate document) might cover this. I've got two files here - one with 2300 lines of code and the other with nearly 6000. Maybe it's time to clean things up?
I guess where I'm coming from is that code attacks a problem domain, and without any description of code in the problem domain context, you're likely to go off the rails.
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
The problem (that we as engineers have been struggling with forever) is that there are two representations of the project - the project as planned and the project as delivered. Any separate document describing the plan is certain to get out of sync with the code, as are comments in the code.
The problem is not unique to programming. How many old buildings have updated (and correct) plans filed with the relevant authorities?
If you have an important point to make, don't try to be subtle or clever. Use a pile driver. Hit the point once. Then come back and hit it again. Then hit it a third time - a tremendous whack.
--Winston Churchill
|
|
|
|
|
Charlie Gilley
<italic>Stuck in a dysfunctional matrix from which I must escape...
"Where liberty dwells, there is my country." B. Franklin, 1783
“They who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.” BF, 1759
|
|
|
|
|
I used to work somewhere that had an automated tool that would deny a code check-in unless the functions were commented. So we used another tool to auto-generate the comments. Things like this always remind of Benjamin from Animal Farm
Quote: Benjamin was the oldest animal on the farm, and the worst tempered. He seldom talked, and when he did, it was usually to make some cynical remark–for instance, he would say that God had given him a tail to keep the flies off, but that he would sooner have had no tail and no flies.
|
|
|
|
|
This morning, while on the bus, I realized that I was the only one reading a real, paper, book...All the other readers used some kind of electronic device...
Does it mean that I'm too old?
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Maybe they read ebook. For example I read a lot of book on my phone
|
|
|
|
|
That's the point - I like the smell and feel of paper books...so I read them in that format and not e(lectronic)book format...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Kornfeld Eliyahu Peter wrote: Does it mean that I'm too old?
Yes, get with the times pops!
New version: WinHeist Version 2.1.1 new web site.
I know the voices in my head are not real but damn they come up with some good ideas!
|
|
|
|
|
Mike Hankey wrote: pops
The first time I ever heard that word was in the 'Legend of 1900' - I loved the movie...
Skipper: We'll fix it.
Alex: Fix it? How you gonna fix this?
Skipper: Grit, spit and a whole lotta duct tape.
|
|
|
|
|
Kornfeld Eliyahu Peter wrote: The first time I ever heard that word was in the 'Legend of 1900' - I loved the movie...
Found it on YouTube...what an awesome movie, thanks!
Tim Roth is a great actor very versatile, saw him recently in "Lie to me" series and "Rob Roy" the movie.
New version: WinHeist Version 2.1.1 new web site.
I know the voices in my head are not real but damn they come up with some good ideas!
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
