Number of code comments is directly proportional to "X" ?
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
Sorry, my code autodocuments itself. When I'm in the need to add a comment to code, I refactor that part of the logic. :-D
"Whether you think you can, or you think you can't--either way, you are right." — Henry Ford "When I waste my time, I only use the best, Code Project...don't leave home without it." — Slacker007
-
Sorry, my code autodocuments itself. When I'm in the need to add a comment to code, I refactor that part of the logic. :-D
"Whether you think you can, or you think you can't--either way, you are right." — Henry Ford "When I waste my time, I only use the best, Code Project...don't leave home without it." — Slacker007
I tend to agree - the more iffy the code I am writing the more comments it has - in general I like the code to explain for itself and I always look at what other peoples code is doing despite any comments they have left because the code doesn't lie - comments are often outdated or just an indication of what the programmer hoped was happening. When I know my code is not doing something obvious I comment it - but I much prefer it to be obvious
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
Dim NumCodeComments as integer 'Number of comments numComments=getRandomNumber() 'getRandomNumber is a general function that returns a random integer. The file can be found... That's my opinion. Look at these comments. Are they: a- necessary ? b- a waste of space & time? c- a bonus? b is my answer. Keep the var names clear, the sub names clear. Sort the code in regions. And most comments become useless, and decrease the readability. If the comment is necessary for someone to understand what's going on, then you're doing something wrong, not following best practises. --> AND THEREFORE, numComments is NOT proportional to skillLevel 'var skillLevel is defined in class... lol I usually remove comments that serve no puropose. Some pseudo code may come in comments sometime precodings, but when it's done, delete the comments.
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
-
Actually I must be getting younger then. I more and more assume that the other programmers are true masters of the obvious and try to comment only what is not so obvious. Documentation comments for classes and methods of course are another case.
And from the clouds a mighty voice spoke:
"Smile and be happy, for it could come worse!"And I smiled and was happy
And it came worse.CDP1802 wrote:
Documentation comments for classes and methods of course are another case.
Ahaa... By suggesting classes and methods should be commented you are confirming the feeling I've had for for years that these constructs are not easy to understand and probably just an 'invention of the devil' to make it harder for us developers to do anything productive in a reasonable amount of time.
Graybeard - back again!
-
CDP1802 wrote:
Documentation comments for classes and methods of course are another case.
Ahaa... By suggesting classes and methods should be commented you are confirming the feeling I've had for for years that these constructs are not easy to understand and probably just an 'invention of the devil' to make it harder for us developers to do anything productive in a reasonable amount of time.
Graybeard - back again!
That's long ago and hard to remember. It must have been the time when I retired my 8 bit Atari and replaced it with a shiny new Atari ST and a C compiler. I really can't remember what it was like to write endless spaghetti Atari BASIC programs :)
And from the clouds a mighty voice spoke:
"Smile and be happy, for it could come worse!"And I smiled and was happy
And it came worse. -
X == experience An old newbie will add less comments than a youngster with some experience. As an old fart 20+ year code monk, I comment BEFORE I code.
Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
I've seen code written by someone with 30 years experience that had almost no comments (and the ones it did have, were wrong because they had not been updated when the code changed). Better yet, this was C code that made use of every trick possible in order to fit in a small embedded system. I've also seen code written by younger people with less experience that has good comments. It's not age or experience. Maybe it's pain experienced by having to support code of the first type?
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
It's all very context-dependent: x = (english literacy)* (philosophical bent)* (domain understanding)* (management emphasis) / (API knowledge) / {coding literacy) / (mastery of graphical methods) / (deadline pressure) Plenty of room there for self-justification...
-
Dim NumCodeComments as integer 'Number of comments numComments=getRandomNumber() 'getRandomNumber is a general function that returns a random integer. The file can be found... That's my opinion. Look at these comments. Are they: a- necessary ? b- a waste of space & time? c- a bonus? b is my answer. Keep the var names clear, the sub names clear. Sort the code in regions. And most comments become useless, and decrease the readability. If the comment is necessary for someone to understand what's going on, then you're doing something wrong, not following best practises. --> AND THEREFORE, numComments is NOT proportional to skillLevel 'var skillLevel is defined in class... lol I usually remove comments that serve no puropose. Some pseudo code may come in comments sometime precodings, but when it's done, delete the comments.
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
X != age and X != experience, because I've seen very senior folks who disdain comments, like some posters here. I write a lot of comments. For me, comments are a conversation I have with myself about what the intent of my code is. Code doesn't capture intent very well; it's too concrete. Code doesn't adequately express the intent of collaboration among multiple modules, because such code is dispersed. Commenting is a discipline that I have spent years training myself to do. Like all writing, comments get better with practice. A person with no practice writing comments typically writes terrible comments, like
x = 1; // assign 1 to x
And surely such a comment is completely useless. Writing comments is a test to see if I understand the code I just wrote. Writing comments frequently causes me to rethink my assumptions, revise my interfaces, and recheck my implementation, to the great improvement of the code. I use unit tests the same way. I am not a hacker. I take a disciplined approach to coding. I like to write code once and be done with it, because it is functional, complete, and correct. Comments help with that. I like to spend my days writing code, not handling interrupts to fix bugs or explain why my code does what it does. Comments help with that too. So manybe X = needs to code something difficult, and needs to teach subsequent programmers what I did
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
CODE tells the computer WHAT to do, COMMENTS tell the human WHY! It doesn't matter what age you are if you can't get that fundamental statement clear in your mind. I find the number of comments in code is dependent on the function of the programmer. I've seen many geniuses in their own mind get themselves into a position where they generate first time code. In other words, this is the first time the function/program/system existed. Being geniuses, it is not their function to do maintenance, therefore they will write crappy code that barely works, using any trick that may have amused themselves and patted themselves on the back for, knowing it was so clever, nobody but a genius like themselves will understand it. They then move on to the next genius project leaving the maintenance (and inevitable changes) to a "lesser" programmer. Hey, guess what role I've usually had. ;P A maintenance programmer will add comments so they know what's going on. So if you are writing first time code and you expect you will be maintaining it, you'll add comments. If you never expect to see this code again, you won't. Age has got nothing to do with it. Maturity, knowing you'll have to look at the code again, and make changes, on a schedule, has. Too many times I've been forced to say the original programmer was a crappy programmer and the changes wanted are impossible to wedge into the current code. This runs counter to their perceptions and you come off as being an untalented whiner.
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
X is the number of years that you have had to maintain your own code. There's no better way to learn that lesson that to have to update code in a system you haven't touched in 3+ years. If you're the type that learns from your mistakes, you will either be glad for the comments you put in or annoyed with yourself; probably both, hopefully more of the former. You are somewhat shielded from this "education" if you work on a large team where you haven't written the whole thing (i.e. you have someone to blame besides yourself:suss:) Just my $0.02, -Chris C.
-
What is X? I think the X would be programmer's age. I have seen the ratio of comments to actual code to be as high as 4:1. Of course, for younger programmer the ratio turns out to be 0. As usual there are some exceptions. Have you found this to be true in your experience?
I am only 26 year old, & I started programming from past one year, I think it is no matter to write lot of comments, It should be just easy to understandable few comments which necessary , start of logic & End of logic...what the purpose to write the that code... hemant singh rautela www.webstrokes.in
-
I do not think this has anything to do with age. This is rather a question of discipline. I've seen "old" programmers who do not write comments at all as well as some which write a lot of comments. The same goes for young programmers. I think this has also something to do with skill, because programmers who comment a lot (and do this the right way) know how important it will be for future development.
I agree with you... I am only 26 year old, & I started programming from past one year, I think it is no matter to write lot of comments, It should be just easy to understandable few comments which necessary , start of logic & End of logic...what the purpose to write the that code... hemant singh rautela www.webstrokes.in
-
X is the number of years that you have had to maintain your own code. There's no better way to learn that lesson that to have to update code in a system you haven't touched in 3+ years. If you're the type that learns from your mistakes, you will either be glad for the comments you put in or annoyed with yourself; probably both, hopefully more of the former. You are somewhat shielded from this "education" if you work on a large team where you haven't written the whole thing (i.e. you have someone to blame besides yourself:suss:) Just my $0.02, -Chris C.
Chris - you just hit the nail on the head with Thor's Hammer. When you maintain code that is 7-10 years old, or you've been working on code that long... the comments helps context.
Charlie Gilley You're going to tell me what I want to know, or I'm going to beat you to death in your own house. "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 am only 26 year old, & I started programming from past one year, I think it is no matter to write lot of comments, It should be just easy to understandable few comments which necessary , start of logic & End of logic...what the purpose to write the that code... hemant singh rautela www.webstrokes.in
hemantrautela wrote:
I am only 26 year old, & I started programming from past one year, I think it is no matter to write lot of comments, It should be just easy to understandable few comments which necessary , start of logic & End of logic...what the purpose to write the that code...
If I understood you correctly: you've been coding 1 year and don't see why you should write lots of comments, since the only thing you would need to code is the start and end of your logic sections and since those are mostly self documenting, you don't see why you would need to do that either. I could be wrong, I've been wrong before... but if I understood you correctly and I were a betting man: I would bet that (assuming you're still coding) you won't completely agree with your previous post 6 years from now. For the record: 1. I don't comment every function/proc in a program, but I do comment many of them (everything that is reused gets a comment) 2. I do always comment when I modify released code 2a. by making notes about what was wrong with the old way, 2b. note how it has changed, 2c. note why it was changed (if known) and 2d. include who told me to do it 2a thru 2d keeps you from getting weird emails months/years later which ask you about stuff you've forgotten... or maybe that's just me :-)
-
hemantrautela wrote:
I am only 26 year old, & I started programming from past one year, I think it is no matter to write lot of comments, It should be just easy to understandable few comments which necessary , start of logic & End of logic...what the purpose to write the that code...
If I understood you correctly: you've been coding 1 year and don't see why you should write lots of comments, since the only thing you would need to code is the start and end of your logic sections and since those are mostly self documenting, you don't see why you would need to do that either. I could be wrong, I've been wrong before... but if I understood you correctly and I were a betting man: I would bet that (assuming you're still coding) you won't completely agree with your previous post 6 years from now. For the record: 1. I don't comment every function/proc in a program, but I do comment many of them (everything that is reused gets a comment) 2. I do always comment when I modify released code 2a. by making notes about what was wrong with the old way, 2b. note how it has changed, 2c. note why it was changed (if known) and 2d. include who told me to do it 2a thru 2d keeps you from getting weird emails months/years later which ask you about stuff you've forgotten... or maybe that's just me :-)