How to comment code?
-
Today is finally a slower day. I needed this Friday to be like this! This week as been absolutely insane and crazy. It is nice for it to be a little bit slow. To top it off my cousin is having her baby. She went into labor today, which is so exciting. My wife and I bought a two family house with her and her husband so we have grown closer and this is so exiting. Now to the real question. I am just wondering how every comments their code. I usually write a small description at the top of my method explaining what it does. I also try to comment anything that may be a little confusing or I will comment things that seem important. Is this a correct practice? What do others do?? Hope everyone has a great Friday! :-D
There are 10 kinds of people in this world. Those who understand binary and those who don't. We shouldn't assume something's debugged just because everyone in the whole world has access to the source code.
Just remember to use lots of swear words: [KID SISTER SWEAR FILTER ON]
if(SomeImportantConditionFailed) { // A***s, the thing is b*****ksed up // I really f*****g hate it when that s**t happens }:-D
-
Just remember to use lots of swear words: [KID SISTER SWEAR FILTER ON]
if(SomeImportantConditionFailed) { // A***s, the thing is b*****ksed up // I really f*****g hate it when that s**t happens }:-D
Ian Darling wrote: Just remember to use lots of swear words yeah! Quick search on http://www.koders.com/ for some swear words says you're right :) David
-
Ian Darling wrote: Just remember to use lots of swear words yeah! Quick search on http://www.koders.com/ for some swear words says you're right :) David
dnh wrote: yeah! Quick search on http://www.koders.com/ for some swear words says you're right shoot, you gave away my favorite English language learning tool.... ;) Actually, I went to school in Tulsa, OK, so I learned to swear like the best of them. I had to unlearn when I returned to New Mexico. As one local commedian said, as you cross the border from Texas to NM the rules change.... "oh sh...oot" _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Today is finally a slower day. I needed this Friday to be like this! This week as been absolutely insane and crazy. It is nice for it to be a little bit slow. To top it off my cousin is having her baby. She went into labor today, which is so exciting. My wife and I bought a two family house with her and her husband so we have grown closer and this is so exiting. Now to the real question. I am just wondering how every comments their code. I usually write a small description at the top of my method explaining what it does. I also try to comment anything that may be a little confusing or I will comment things that seem important. Is this a correct practice? What do others do?? Hope everyone has a great Friday! :-D
There are 10 kinds of people in this world. Those who understand binary and those who don't. We shouldn't assume something's debugged just because everyone in the whole world has access to the source code.
there is no consensus in the office where i work on commenting, and there are only 3 of us here at the moment *rolls eyes* if it is my code then i know i am likely to be maintaining and bug fixing it for years to come, so i do a few things that help me personally: * i put a "block comment", 2 long lines of *'s at the head of each function. this helps me spot functions when running up and down a file at speed. please don't tell me all about the wonders of the IDE, since i do a certain amount of editing in VIM, or even VI. for me this is a proven strategy. on good days i even put comments about what the function does in there. * i put in comments explaining what and why i was doing anything strange, since the code may make sense, but i *really* need to understand *why* it is doing what it is doing * i put references to the spec where required for "stupid" code rules from my experience the level of commenting is not that high, it is higher than i want to bother doing (i am lazy like that) but i do it anyway since the benefits out way the costs. as far as i am concerned if this is not true, then there is something seriously wrong with your commenting method, regardless of how you do it :) zen is the art of being at one with the two'ness
-
Today is finally a slower day. I needed this Friday to be like this! This week as been absolutely insane and crazy. It is nice for it to be a little bit slow. To top it off my cousin is having her baby. She went into labor today, which is so exciting. My wife and I bought a two family house with her and her husband so we have grown closer and this is so exiting. Now to the real question. I am just wondering how every comments their code. I usually write a small description at the top of my method explaining what it does. I also try to comment anything that may be a little confusing or I will comment things that seem important. Is this a correct practice? What do others do?? Hope everyone has a great Friday! :-D
There are 10 kinds of people in this world. Those who understand binary and those who don't. We shouldn't assume something's debugged just because everyone in the whole world has access to the source code.
BrockVnm wrote: What do others do?? I've experienced a couple of times the situation, where I had to look into code that I've written a couple of years ago and I felt angry that I didn't comment the stuff correctly. I've learned my lessions. Today I fully comment each and every public method of any class to a maximum extend (private methods are explained with little less effort):
- Short description of what the method does
- If it's a complex method I additionally provide information on how the task is accomplished
- Valid input for each parameter
- Description of the return value
- Possible exceptions thrown
I'm using the XML-Commenting features which I find useful eventhough they are messing up the readability of the file to some extend. But to me it seems, writing a lot of comments isn't the whole story. I try hardly to keep my comments updated when code changes occur. Another thing I find quite often when reading code (luckily not my own) is senseless comments. I regularly ask myself on what trips the coders might have been which explain Generates a random number just before the method
GenerateRandomNumber(). Very helpful, idiot thanks. Just my 2 cent. /matthiasI love deadlines. I like the whooshing sound they make as they fly by.
[Douglas Adams] -
dnh wrote: yeah! Quick search on http://www.koders.com/ for some swear words says you're right shoot, you gave away my favorite English language learning tool.... ;) Actually, I went to school in Tulsa, OK, so I learned to swear like the best of them. I had to unlearn when I returned to New Mexico. As one local commedian said, as you cross the border from Texas to NM the rules change.... "oh sh...oot" _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
:) David
-
Today is finally a slower day. I needed this Friday to be like this! This week as been absolutely insane and crazy. It is nice for it to be a little bit slow. To top it off my cousin is having her baby. She went into labor today, which is so exciting. My wife and I bought a two family house with her and her husband so we have grown closer and this is so exiting. Now to the real question. I am just wondering how every comments their code. I usually write a small description at the top of my method explaining what it does. I also try to comment anything that may be a little confusing or I will comment things that seem important. Is this a correct practice? What do others do?? Hope everyone has a great Friday! :-D
There are 10 kinds of people in this world. Those who understand binary and those who don't. We shouldn't assume something's debugged just because everyone in the whole world has access to the source code.
See the book, Code Complete by Steve McConnell. Also see the chapter on style in Object-Oriented Software Construction by Bertrand Meyer. I try to follow their recommendations but even so I find that commenting is a never-ending learning exercise. The main problem I find with comments, from the point of view of a maintenance programmer, is the lack of intent comments from developers, specifically why they are doing a particular operation. It's a failing I have as well but I strive to improve. Kevin
-
Today is finally a slower day. I needed this Friday to be like this! This week as been absolutely insane and crazy. It is nice for it to be a little bit slow. To top it off my cousin is having her baby. She went into labor today, which is so exciting. My wife and I bought a two family house with her and her husband so we have grown closer and this is so exiting. Now to the real question. I am just wondering how every comments their code. I usually write a small description at the top of my method explaining what it does. I also try to comment anything that may be a little confusing or I will comment things that seem important. Is this a correct practice? What do others do?? Hope everyone has a great Friday! :-D
There are 10 kinds of people in this world. Those who understand binary and those who don't. We shouldn't assume something's debugged just because everyone in the whole world has access to the source code.
One technique I have found to be very useful is to place function comments between the declaration line and the opening brace. I have seen far too many instances of comments that are placed above the function, surrounded by nice rows of "asterski" (plural of asterisk), nicely lined up, and full of information. But, they become victims of cut and paste when programmers (myself included) copy the entire function but mostly ignore everything around it. The function gets copied, but not the comment. By having any comments just before the opening brace, the comment becomes part of the function and it takes an active role to copy the function without the comment. Fewer comments get lost that way. Dave "You can say that again." -- Dept. of Redundancy Dept.
-
there is no consensus in the office where i work on commenting, and there are only 3 of us here at the moment *rolls eyes* if it is my code then i know i am likely to be maintaining and bug fixing it for years to come, so i do a few things that help me personally: * i put a "block comment", 2 long lines of *'s at the head of each function. this helps me spot functions when running up and down a file at speed. please don't tell me all about the wonders of the IDE, since i do a certain amount of editing in VIM, or even VI. for me this is a proven strategy. on good days i even put comments about what the function does in there. * i put in comments explaining what and why i was doing anything strange, since the code may make sense, but i *really* need to understand *why* it is doing what it is doing * i put references to the spec where required for "stupid" code rules from my experience the level of commenting is not that high, it is higher than i want to bother doing (i am lazy like that) but i do it anyway since the benefits out way the costs. as far as i am concerned if this is not true, then there is something seriously wrong with your commenting method, regardless of how you do it :) zen is the art of being at one with the two'ness
feline_dracoform wrote: i put in comments explaining what and why i was doing anything strange, since the code may make sense, but i *really* need to understand *why* it is doing what it is doing Yep. This is the biggest failing among programmers. Kevin
-
there is no consensus in the office where i work on commenting, and there are only 3 of us here at the moment *rolls eyes* if it is my code then i know i am likely to be maintaining and bug fixing it for years to come, so i do a few things that help me personally: * i put a "block comment", 2 long lines of *'s at the head of each function. this helps me spot functions when running up and down a file at speed. please don't tell me all about the wonders of the IDE, since i do a certain amount of editing in VIM, or even VI. for me this is a proven strategy. on good days i even put comments about what the function does in there. * i put in comments explaining what and why i was doing anything strange, since the code may make sense, but i *really* need to understand *why* it is doing what it is doing * i put references to the spec where required for "stupid" code rules from my experience the level of commenting is not that high, it is higher than i want to bother doing (i am lazy like that) but i do it anyway since the benefits out way the costs. as far as i am concerned if this is not true, then there is something seriously wrong with your commenting method, regardless of how you do it :) zen is the art of being at one with the two'ness
feline_dracoform wrote: please don't tell me all about the wonders of the IDE, since i do a certain amount of editing in VIM, or even VI. uh uh feline_dracoform wrote: * i put in comments explaining what and why i was doing anything strange, since the code may make sense, but i *really* need to understand *why* it is doing what it is doing feline_dracoform wrote: but i do it anyway since the benefits out way the costs. as far as i am concerned if this is not true, then there is something seriously wrong with your commenting method, regardless of how you do it :cool: 5 David
-
Today is finally a slower day. I needed this Friday to be like this! This week as been absolutely insane and crazy. It is nice for it to be a little bit slow. To top it off my cousin is having her baby. She went into labor today, which is so exciting. My wife and I bought a two family house with her and her husband so we have grown closer and this is so exiting. Now to the real question. I am just wondering how every comments their code. I usually write a small description at the top of my method explaining what it does. I also try to comment anything that may be a little confusing or I will comment things that seem important. Is this a correct practice? What do others do?? Hope everyone has a great Friday! :-D
There are 10 kinds of people in this world. Those who understand binary and those who don't. We shouldn't assume something's debugged just because everyone in the whole world has access to the source code.
Sounds like a fun weekend. Generally, I start out with psuedocode comments and insert code where appropriate. I try to use self documenting variables and routines to keep things clear. At the top of a function, I'll include a summary of it's purpose including return values, a list of parameters, their purpose and whether they are input or output, and list of changes in reverse chronological order. [on Get/Set type functions I don't usually bother with explainations] if needed I try to explain why I chose the methodology I did, and maybe if I couldn't get something esle more obvious to work. [some of these are goals of mine, and not always put into practice, i'm sort of lazy (surprise, surprise)] Also, I leave old code commented out until it's apparent what I replaced it with is working fine. BW
All the chickens get it.
And them singing canaries get it.
Even strawberries get it.[
Discovering BPI
-
feline_dracoform wrote: please don't tell me all about the wonders of the IDE, since i do a certain amount of editing in VIM, or even VI. uh uh feline_dracoform wrote: * i put in comments explaining what and why i was doing anything strange, since the code may make sense, but i *really* need to understand *why* it is doing what it is doing feline_dracoform wrote: but i do it anyway since the benefits out way the costs. as far as i am concerned if this is not true, then there is something seriously wrong with your commenting method, regardless of how you do it :cool: 5 David
so far i have yet to make the IDE run in console mode on a UNIX box, so all such programming is done in good old VIM :) in fact a certain amount of windows programming is done in VIM, which is used when ever i hit the limits of the IDE, and want fast, powerful and easy macro support. but this is a whole different discussion :) zen is the art of being at one with the two'ness
-
Today is finally a slower day. I needed this Friday to be like this! This week as been absolutely insane and crazy. It is nice for it to be a little bit slow. To top it off my cousin is having her baby. She went into labor today, which is so exciting. My wife and I bought a two family house with her and her husband so we have grown closer and this is so exiting. Now to the real question. I am just wondering how every comments their code. I usually write a small description at the top of my method explaining what it does. I also try to comment anything that may be a little confusing or I will comment things that seem important. Is this a correct practice? What do others do?? Hope everyone has a great Friday! :-D
There are 10 kinds of people in this world. Those who understand binary and those who don't. We shouldn't assume something's debugged just because everyone in the whole world has access to the source code.
Comments should always show intent, context and expectations for every method and every bit of tricky code inside the method. Whenever this subject comes up here, a significant number of people seem to think that code should be completely self documenting and therefor require almost no comments at all. Those people are either inexperienced or idiots, disregard them completely if you get that kind of answer. I've been programming for decades now and if any programmer working for me followed this attitude their employment would be very short if they didn't change their ways although I doubt I would hire anyone that inexperienced in the first place unless it was a training thing. Sure, well written code is *easier* to understand than poorly written code, but the most well written code ever is still a mystifying jumble when you look at it months or years later and don't remember the context of what you intended at the time. Experience will tell you what to do which mainly is to document the intent of any bit of code that isn't completely clear. If you ever have to go back and re-work code that you wrote more than a year ago on any regular basis you will start to get a feel for what you need to do. The main problem is usually along the lines of "but what does it *do*?" or "why did I do it that way?" or more often than not "why is it even here in the first place?". Knowing what the programmer intended and expected of any bit of gnarly code is half the battle. Every method should be documented at it's top to indicate what it's for and what it does, who calls it and what the parameters are for and what is returned. Any part of the code inside the method that has any potential for being confusing should first be re-examined to ensure it is written as clearly and simply as possible, then secondly commented as to it's intent and expected operations. In particular watch out for code that to you seems simple enough but taken out of context is very confusing. A common problem is that you find a bug and need to fix something long after it was written, you're busy working on other stuff and don't have the time to fully grasp what you're looking at. When you wrote it originally it was in the mental context of all the code you were writing at the time and may have seemed simple and made perfect sense in that mental context, but now finding the exact method that's crashing, you look at it and in your new mental context of all the other stuff your working on your brain doesn't want to drop all that
-
Yes it is! No it isn't! Lets just get it over with. The opinions on this will range from no comments are fine since code is self commenting to every line of code should be commented. It sounds like you are doing an average job. Less documentation than I do, but I realize I do more than most. Tim Smith I'm going to patent thought. I have yet to see any prior art.
Tim Smith wrote: to every line of code should be commented. I was searching through my old boxes for my program from college. I kept one, but I can't find it. The T/A always wrote on every assignment "not enough comments". I finally got so fed up, on one assignment I put a header comment that said in English the full intent and functionality, followed by the full function in psuedo-code, followed by the function with each line commented at the end with an explanation of function of that line (including "Begin" commented with "Begin function" and "End" commented with "End Function"). I wanted to show you could go too far in commenting. The only lines that did not have at least one comment were blank lines (at least 3) separating functions. It took forever, it was grossly redundant, and it was meant to prove ad absurdum by being over the top. The T/A wrote "Best commenting job in the college! Keep it up!" :wtf: _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Comments should always show intent, context and expectations for every method and every bit of tricky code inside the method. Whenever this subject comes up here, a significant number of people seem to think that code should be completely self documenting and therefor require almost no comments at all. Those people are either inexperienced or idiots, disregard them completely if you get that kind of answer. I've been programming for decades now and if any programmer working for me followed this attitude their employment would be very short if they didn't change their ways although I doubt I would hire anyone that inexperienced in the first place unless it was a training thing. Sure, well written code is *easier* to understand than poorly written code, but the most well written code ever is still a mystifying jumble when you look at it months or years later and don't remember the context of what you intended at the time. Experience will tell you what to do which mainly is to document the intent of any bit of code that isn't completely clear. If you ever have to go back and re-work code that you wrote more than a year ago on any regular basis you will start to get a feel for what you need to do. The main problem is usually along the lines of "but what does it *do*?" or "why did I do it that way?" or more often than not "why is it even here in the first place?". Knowing what the programmer intended and expected of any bit of gnarly code is half the battle. Every method should be documented at it's top to indicate what it's for and what it does, who calls it and what the parameters are for and what is returned. Any part of the code inside the method that has any potential for being confusing should first be re-examined to ensure it is written as clearly and simply as possible, then secondly commented as to it's intent and expected operations. In particular watch out for code that to you seems simple enough but taken out of context is very confusing. A common problem is that you find a bug and need to fix something long after it was written, you're busy working on other stuff and don't have the time to fully grasp what you're looking at. When you wrote it originally it was in the mental context of all the code you were writing at the time and may have seemed simple and made perfect sense in that mental context, but now finding the exact method that's crashing, you look at it and in your new mental context of all the other stuff your working on your brain doesn't want to drop all that
John Cardinal wrote: Every method should be documented at it's top to indicate what it's for and what it does, who calls it and what the parameters are for and what is returned. Did you mean this? Are you suggesting that if a new bit of development calls a function in a stable, checked-in source file, I should check out the file with the called function, and update its comment?
-
One technique I have found to be very useful is to place function comments between the declaration line and the opening brace. I have seen far too many instances of comments that are placed above the function, surrounded by nice rows of "asterski" (plural of asterisk), nicely lined up, and full of information. But, they become victims of cut and paste when programmers (myself included) copy the entire function but mostly ignore everything around it. The function gets copied, but not the comment. By having any comments just before the opening brace, the comment becomes part of the function and it takes an active role to copy the function without the comment. Fewer comments get lost that way. Dave "You can say that again." -- Dept. of Redundancy Dept.
David Chamberlain wrote: The function gets copied, but not the comment. Sounds like a good idea to me. Faced with the choice of having a function with a) no comments b) wrong comments, because the cut-and-paster forgot to modify them afterwards I'll pick no comments every day. Wrong comments are *much* worse than none.
-
dnh wrote: yeah! Quick search on http://www.koders.com/ for some swear words says you're right shoot, you gave away my favorite English language learning tool.... ;) Actually, I went to school in Tulsa, OK, so I learned to swear like the best of them. I had to unlearn when I returned to New Mexico. As one local commedian said, as you cross the border from Texas to NM the rules change.... "oh sh...oot" _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
Jeffry J. Brickley wrote: I went to school in Tulsa, OK... I've been in Tulsa since 1991. :-D
"Ideas are a dime a dozen. People who put them into action are priceless." - Unknown
-
Jeffry J. Brickley wrote: I went to school in Tulsa, OK... I've been in Tulsa since 1991. :-D
"Ideas are a dime a dozen. People who put them into action are priceless." - Unknown
DavidCrow wrote: I've been in Tulsa since 1991. Only 1985 for me, Bryan Institute of Tulsa, OK. I went there after I dropped out of College at the University of New Mexico. Mostly to get away from family. :) _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
John Cardinal wrote: Every method should be documented at it's top to indicate what it's for and what it does, who calls it and what the parameters are for and what is returned. Did you mean this? Are you suggesting that if a new bit of development calls a function in a stable, checked-in source file, I should check out the file with the called function, and update its comment?
I don't mean exact functions in terms of who calls it, more like who generally would call it I guess, at least that's how I comment. It's a reminder in part of why it's there in the first place in terms of what function it provides in the context of the whole program. It wouldn't apply of course to a general purpose library of some kind where anyone and anything might be using it in all different contexts and even different applications.
"A preoccupation with the next world pretty clearly signals an inability to cope credibly with this one."
-
Sounds like a fun weekend. Generally, I start out with psuedocode comments and insert code where appropriate. I try to use self documenting variables and routines to keep things clear. At the top of a function, I'll include a summary of it's purpose including return values, a list of parameters, their purpose and whether they are input or output, and list of changes in reverse chronological order. [on Get/Set type functions I don't usually bother with explainations] if needed I try to explain why I chose the methodology I did, and maybe if I couldn't get something esle more obvious to work. [some of these are goals of mine, and not always put into practice, i'm sort of lazy (surprise, surprise)] Also, I leave old code commented out until it's apparent what I replaced it with is working fine. BW
All the chickens get it.
And them singing canaries get it.
Even strawberries get it.[
Discovering BPI
brianwelsch wrote: Also, I leave old code commented out until it's apparent what I replaced it with is working fine Yeah, I always do that to. brianwelsch wrote: if needed I try to explain why I chose the methodology I did, and maybe if I couldn't get something esle more obvious to work. Good point. I can remember several times when I looked at old code and wondered why I didn't do it a different way only to later remember that the shortcut wasn't valid, I now make sure I explain why I did something a particular way when it's not obvious at a quick glance.
"A preoccupation with the next world pretty clearly signals an inability to cope credibly with this one."