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.
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."
-
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 have commented functions to say "called by X()" before now. however i normally only do this when this function should only ever be called by X(), since what it does is related to X(), and the expected context of X(). for other things, like strlen() this is a bit overkill :) i suspect "common sense" and "experience" are required here. oh dear ;) 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.
The rule for me is to use descriptive words for function names and variables. The only two notations I use in C/C++ are the "p" prefix for pointers and the "h" prefix for handles. For example, two weeks ago I wrote a function called
InternetBackupAuthorize(). There is no need to add a comment describing it's use since it's blazingly obvious what it's for. If you can't figure it out, then you have no business looking at the code in the first place. Anyone who thinks he has a better idea of what's good for people than people do is a swine. - P.J. O'Rourke -
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.
It depends on the language. When I code in assembler I comment every line (on the same line) and block comment the procedures. My mantra when coding assembler is if I cannot think of a meaningful comment to put on the line of code it doesn't belong in the program. When I code in C, C++, C# I block comment the procedures and also the structure so I know which "}" (ending brace) goes with which condition e.g. /* This procedure does Blah, Blah, Blah, ... */ if(SomeCondition){ while(SomeOtherCondition){ execute this code and repeat executing until !SomeOtherCondition } // while(SomeOtherCondition) } // if(SomeCondition) else{ execute this code when !SomeCondition } // else [if(SomeCondition)] or } /* else [if(SomeCondition)] */ for C language When coding in a language like VB (shows you what depths I will sink to for money) I usually only block comment the procedures because the language is so mind-numbingly (is that a word?) verbose that the code tends to be self commenting. Self commenting sounds like a good thing until you get writer's cramp tryinng to code anything more complex than a simple read a file (or database) and propogate a listbox. I also tend to forget what comes next because I have spent so much time filling in the syntax and not paying attention to what it is I am trying to accomplish with the code. How I choose what programming language I use depends on what I want to get accomplished. If I can code it in C++ I do, sometimes with embedded assembler code to do what is not easily accomplished with C++. If and only if the client insists I will use VB. I try to reason with them but it is their system and if they want to live with the limitations of VB I can do it for them. I told you I had no pride when money is involved. Well maybe a little pride as I will not do anything illegal but I do have a life outside of work so if you want me to code in VB I will do a good job of it and walk away at the end of the day with my ego intact. I tend not to develop for .NET (C#) unless the client specifically wants to target the .NET architecture. Usually this only happens when writing for a captured audience (in house systems). If they are planning to resell the product they usually do not want to force their clients to install the .NET runtime libraries if not needed (WinNT, Win2000) so the requirement usually calls for C++. Hope this helps. JimmyRopes
-
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.
This is a bit like the way Eiffel functions are commented e.g., find_customer is -- Find a customer do -- code end More logical really. Kevin