How to comment code?
-
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
-
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: 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] I always go for at least a function summary. I don't always add the other bits. However, with the newer languages which have code comment tags, e.g., C#'s doc comments, I increasingly make use of the other bits you refer to. Many, however, don't even bother with a function summary. brianwelsch wrote: I try to use self documenting variables and routines to keep things clear. Yep. Another good, but underused technique, is the "replace conditional with boolean" refactoring. I use this frequently and it allows you to eliminate the comment. Comments should be many as necessary but as few as possible. That way you minimise the ever-constant danger of comments and code getting out of synch. Sometimes what you do is start writing a lengthy comment and doing that makes it clear to yourself how to rewritethe code to reduce the length of the comment. brianwelsch wrote: Also, I leave old code commented out until it's apparent what I replaced it with is working fine. Yes, I do this too. However, if working with source control, then when the project is finished, or prior to its being released in some way, you should get rid of all commented out code. I find that looking at production code which still contains commented out sections is distracting and also can make code blocks hard to read. Kevin
-
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
Maybe it's not so much saying who calls it but why anyone would call it. Kevin
-
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: Comments should always show intent, context and expectations for every method and every bit of tricky code inside the method. Yes. We all also ought to be using techniques such as design by contract (DbC) but unfortunately most languages don't support it very well. Kevin