|
Hi.
I am a C++ programmer with experience with MFC and Winsock. I am working on project that utilize MFC, Winsock, and more advanced C++ like that found in Modern C++ Design. I have a question about writing commends.
I hate writing comments! Before you go off and post about responses, please consider my reasons. I understand the importance of comments from in terms of team project. In a team project where hundred and even thousands of programmers study and modify each other's code, comments are imperative. Comments are essential even in individual projects. Experienced programmers understand that we will one day read code we worked on six months ago. The bottomline is that comments are imperative to software implementation especially with C++ where some section of a code can be abstract and different to decipher.
Nonetheless, comments are tedious! For example, let say you spend an hour on an algorithm. Now, you have to spend another ten, twenty, even thirty minutes commenting the class or a collection of classes. In the end, you have less time solving other problems.
I want to know how do you programmers deal with commends in real-world team projects. Real-world projects vary from a simple simulation for NASA to an operating system. I know I am developing a bad habit that will hurt me in the end, but sometimes I get so caught up in solving problems that I ignore the comments. I remember all my code. Somethings I take a few minutes to see what goes on, but I always recommend it. Again, I understand the reason is because I am the person who wrote it.
Lastly, is there an art to writing good comments? How do you know where, when, and what to write such that the comment is elegant and takes up little time and effort because it becomes natural?
Thanks,
Kuphryn
|
|
|
|
|
There was a time not too long ago that I would have agreed that comments are tedious and at best a "necessary evil".
kuphryn wrote:
Nonetheless, comments are tedious! For example, let say you spend an hour on an algorithm. Now, you have to spend another ten, twenty, even thirty minutes commenting the class or a collection of classes. In the end, you have less time solving other problems.
One thing I have learned that helps me quite a bit is this. Anytime I have need to write a new class, start by commenting the class and then writing the code with inline comments. (By inline comments, I mean comments on important lines.)
kuphryn wrote:
get so caught up in solving problems that I ignore the comments
I might add that by not commenting you are only introducing future problems.
kuphryn wrote:
Lastly, is there an art to writing good comments? How do you know where, when, and what to write such that the comment is elegant and takes up little time and effort because it becomes natural?
For me it has taken a very long time (years) to get to the point where I comment first and then code. I have learned that this helps me in several ways not the least of which is it helps me to remain focused on the implementation I have chosen and not to try and gold-plate it or (wing it) as I go. The key to doing this, though is knowing in advance what I am going to write and not writing it until I have it figured out in my head or sometimes in a testbed.
Once I made the leap from the "code a solution" to "design a solution and then code it" it became clear that commenting had to come first.
Anyway, that's just my 2 cents.
|
|
|
|
|
Interesting...I don't know if you taught yourself how to program or if you were taught by someone. Teacher, friend whatever. From day one I always commented first then wrote code and refined both as I went on writting.
This would make for an interesting POLL question...
Chris...I think this should be a poll...
I always thought thats how everyone programmed.
"An expert is someone who has made all the mistakes in his or her field" - Niels Bohr
|
|
|
|
|
You bring up a very interesting point. I hate writing comments too, however, I do write them. But I have to admit that my comments do not follow any specific methodology. I have seen code where each class has comments. Each function has detailed comments before the function etc. However, I have also found that some of these comments are very bookish. For example:
/* Function Name: SumOfBlah
Author : Son of Blah
Parameters/Arguments: int one and int two
Returns : int
Purpose : Adds one and two and returns the resulting value
*/
Or something like that. Now if the function were merely adding then these comments are OK. But if the function were not sum and instead was some complex algorithm such as "Determines the meaning of life." Then I find that merely stating that like in the sample above does very little for me. I need to know, how you determined "the meaning of life." i.e., comments should not be written for the sake of writing them, but more so to explain just what the hell is happening in there. 
What I tend to do is write comments as I write the code. Just a few words to explain what and why I am doing.
And I have to say I love it when other developers do the same. I have had to deal with code with no documentation and no comments that dealt with various forecasting algorithms. And this code not only had no comments but used variables like i1, i2 ...etc. Goes without saying.... I rewrote the damn code rather than trying to fix the bloody thing. On the other hand I have found code well commented in Russian...no problem.... called a russian friend who told me what it said...and bingo!!! code fixed in a few hours. Comments do help.....
So where do I stand on comments:
1. A brief description for each function/class...if necessary
2. Comments in the code as I write the code. (very critical)
3. Write code in a self documenting manner, i.e., use class names, variable names, function names that make sense. (very critical)
Where do my bosses stand on Comments:
Those bookish comment blocks above each function which may or may not provide any useful information, but they look pretty, cover the bosses rear end, and provide the impression of well documented work... I hope they don't read this...
And by the way.... my comments have come to my own rescue, 2 years and 4 projects later. Its not always that easy to recall, why you did something... hehehehehehe   ;)
|
|
|
|
|
I can't say I've ever collaborated on any project other than sharing code with friends and sometimes re-working scripts and code snippets I get from sites like CP. However the importance of commenting IMO is crucial, it takes me twice as long to figure code when there are no comments...code context isn't enough...not as bad as trying to figure out assembly I agree, but still comments make a huge difference.
I personally comment about every second line of code, yes I have a 1:2 ratio on average according to some source code metrics tool I downloaded a while ago. The link is available somewhere under a CP article I sometimes catch myself writting to many comments...like
char* pChar = &Phantom[0];
When in reality only the most virgin newbie wouldn't understand what that code is doing just by analyzing context of the code.
As far as writting code and back tracking...? The one friend of mine who I occasionally team up with on web projects does that very same thing. Im the opposite...I code as I write...for starters I think it allows for better code seperation when using a color syntax supported IDE like VS. When I have written over 500 lines in one module and I catch a bug while testing and I know whats causing it it's easy for me to find the function and then the peice of code. To me commenting is an integral part of programming like color syntax hilighting. It's a tool and you might as well use it if it makes you time easier and not if it's a personal burden. However I guess as a team member it's essential...cuz if you had fellow coders like me, you'd hear nothing but whinning and complaining.
Just my opinion
Cheers!
"An expert is someone who has made all the mistakes in his or her field" - Niels Bohr
|
|
|
|
|
Okay. Thanks.
I have decided to adopt an algorithm-based approach to commenting. I will comment every function with one line descripting the function. Otherwise, I will commend at the beginning of every algorithm, not lines of code. For example, "a = 5" is not important. It is the algorithm that is important, i.e. Why a = 5? I have been using this approach for the last couple of months.
Kuphryn
|
|
|
|
|
I can sum it up with this statment: Part of your job as a professional programmer is to write code that others are able to read and maintain.
If you think "oh I'll go back to comment it later" you're fooling yourself. You won't have time later to go comment it, you'll be working on bugfixes or features for the next revision.
kuphryn wrote:
In the end, you have less time solving other problems.
Commenting your algorithms so the other team members can read the code is part of the algorithm-writing process. So don't think of it as "1 hour to write the code, 20 minutes for the bloody comments", think of it as "1 hour 20 min to finish the entire task."
Skipping 20 minutes up front to write good documentation will most certainly cost the team more than 20 minutes later when someone else has to fix a bug in the code, but first they have to stare at it and step through it to understand what it's supposed to do. Or worse, call you over so you can explain it, which will cost two people time.
--Mike--
"alyson hannigan is so cute it's crazy" -- Googlism
Just released - 1ClickPicGrabber - Grab & organize pictures from your favorite web pages, with 1 click!
My really out-of-date homepage
Sonork-100.19012 Acid_Helm
|
|
|
|
|
My simple approach to comments is,
Explain why I did something not what I did.
It's pointless trying to explain what the code is doing as that should be obvious from the code. However you should always say why you did something. This helps you when you go back to the code and wonder why the code is doing what it does.
I also document public class members, so that if somebody reuses the class then they know what the interface does and what parameters are needed. Anything private doesn't usually get a function header. I like people take a black box approach, documenting those functions that are specified in the design document but not really caring about the internal implementation.
Michael
Life’s not a song.
Life isn’t bliss.
Life is just this.
It’s living. -- Buffy the Vampire Slayer: Once more, with feeling
|
|
|
|
|
The best advice I ever received on commenting was this:
"If you can say it in code, do so. Otherwise, say it in a comment." - Dan Saks, secretary of the ANSI C++ Standard committee
In other words, you should write your code to be as readable as possible. The more readable your code is, the less commenting you should need to do to explain it.
There are all sorts of things you do to make your code readable:
- Have a naming convention. Define the convention so that you can look at a variable name and tell important things about the name without looking up its definition.
- Use descriptive names. Names like ClassX, ClassQ23, don't tell you anything about what they do. Names like BuyerClass, SellerClass, KernelWaitForCrash() tell you what they are about.
- Use a consistent style: Place braces, parentheses, etc. consistently.
- Code conservatively. For example, just because you can override the multiplication operator for two strings doesn't mean you should do so.
- If you work with other people, sit down at the start of a project and agree on how you're going to do these things.
Software Zen: delete this;
|
|
|
|
|
Okay. Thanks everyone.
After reading many responses, I will sum commenting techniques I believe are essential and has been or will adopt.
// I have began adopting this convention in all my projects after
// learning MFC via Jeff Prosise a year ago.
- Use descriptive function and variable names (Ranjan Banerji, Gary R. Wheeler, and alnite agree)
Example: MoveCityMapRight()
DeleteCityMapPointer()
PaintCityMapBottomSection()
defaultCityMap
newCityMap
cityMapTopSection
cityMapCenterPoint
- Write comments while coding (by Ranjan Banerji)
This is a very useful commenting technique. I will definitey adopt this technique in that I add concise
comments on algorithms and code I believe are essential as I type them. Key word is "concise."
// This technique is basic, but I bet more programmers choose to write general comments over this technique.
- Write comments on *why* you chose an algorithm (by Michael P Butler)
I agree with Butler on this commenting technique. A piece of code might contain 1000 lines with 500 lines of comments.
Nonetheless, they are meaningless unless the reader understand the fundamention of the algorithm and why it was used.
Write a whore analysis of the algorithm.
- Elegant design, good and clear code top priority list (by whoie)
This is software design and implementation wisdom!
Kuphryn
|
|
|
|
|
In our organisation we use http://www.doxygen.org/ style comments. The rule is that a code not documented with doxygen style is not accepted in production software.
It doesn't mean that each member/function must be documented, but all the key ones must be.
loic
|
|
|
|
|
I am having a problem that I can't seem to figure out. I wrote a COM server that does file i/o in c++. When I tested my code outside the COM server as a standalone app, it correctly performed all file i/o. However, when the same code is packaged inside a COM server, even though I specify an absolute path: C:\my_file.txt, in an fopen() call, it writes to a file that is in the same folder as the VB client executable.
It wouldn't be such a problem, except now I want to call the code in IIS4, and I have no idea where to put my files.
i've built this COM server. From within this COM Server, I called fopen to do read/write. I have two options:
(a) relative path: I expect the file to be in the same directory of the client if its a VB client. If the client is an ASP app and I am using IIS4, then it should be in the same folder as "inetinfo.exe"?? Is this understanding correct?
(b) absolute path: It doesn't matter whether the client is a VB client or an ASP application, it should be located in the directory specified: "C:\myfile.txt".
My code inside the COM server is:
FILE * pFile;
pFile = fopen ("C:\myfile.txt","wt"); //Or I can use relative path.
if (pFile!=NULL)
{
fputs ("fopen example",pFile);
fclose (pFile);
}
Note: There're two type of client:
(a) ASP application + IIS
(b) VB Client
Thanks!
norm
|
|
|
|
|
You need to use a double backslash, like "c:\\myfile.txt" otherwise your compiler don't see it as a \
- Anders
Money talks, but all mine ever says is "Goodbye!"
|
|
|
|
|
Does anyone know how to enumerate the memory slots on the motherboard and determin the configuration of the memory installed?
I need to do this for a project I am working on and I can't find any documentation on this subject.
|
|
|
|
|
I don't think you can do this on newer systems like XP or even 98 for that matter, but I seem to recall this information is determined by the bios and stored inside the CMOS which can be accessed using crt inp() and outp() functions on port 78h I think...i'm not sure...
I could be totally off or relatively close, it's been a while since I glaced at low-level programming.
Cheers!
"An expert is someone who has made all the mistakes in his or her field" - Niels Bohr
|
|
|
|
|
I need to find differences between two large chunks of memory where the differences themselves are fairly small.
I have downloaded GNU diff sources (Eugene Meyers?) and need to compare performance on my data with other diff-algorithms, like McIlroy-Hunt.
I have only basic knowleadge on the topic, so any webresources or book recommendations would be greatly appreciated.
Thanks
/moliate
The corners of my eyes catch hasty, bloodless motion -
a mouse?
Well, certainly a peripheral of some kind.
Neil Gaiman - Cold Colours
|
|
|
|
|
This may be overkill for your needs, but check out:
http://sourceforge.net/projects/xdelta/[^]
Shog9
------
That why you have a dual processor system. One for system, one for the screen saver - Mark Nischalke on Win2k server administration
|
|
|
|
|
Looks very interesting. I've printed the article and will read it tonight.
Thanks a lot!
/moliate
|
|
|
|
|
nice discussion here[^]
The problem with a big chunk of memory is the pure size of the string.
Most diff-like programs use something other than a byte or character
as the basic string element. (e.g. a line of text is probably the most
common string element for the diff algorithm. hence the 'string' is
really only as long as the number of lines in the file.)
If you can give up the minimum # of byte changes in the two
memory blocks, you can get better performance by using some suitable
'chunk' definition to break up memory into the elements of the strings
to be passed for diff analysis.
I'm no expert on this but was implementing something similar just
recently where the diff was first calculated on our chunks, and only
if the changed regions were small, would a finer intra-chunk diff be
performed.
Be careful though, your chunk definition should have the property
that changes naturally fall within chunks, not across chunk boundaries.
|
|
|
|
|
Thanks.
My problem is mostly that the string cannot be divided into natural chunks, meaning that the insertion of a single byte could impose a lot of extra processing.
I'll look more closely at the PERL code for the LCS. It seems to have some memory improvements over full table LCS, which is very nice when working with strings of 100kb each.
Cheers
/moliate
The corners of my eyes catch hasty, bloodless motion -
a mouse?
Well, certainly a peripheral of some kind.
Neil Gaiman - Cold Colours
|
|
|
|
|
hiya i want to extract a dialog box i have made with Insert->Resource and use it in a completely different program or programs.
is there a way of doing this??
thanks
grahamoj.
|
|
|
|
|
You need to manually copy it's template from the .rc file and copy into the new ones. All items in it will have a name, they will have to be manually added with new values into the list of resource ID's, and the value at the bottom of the file for next available ID will also need to be incremented.
Christian
No offense, but I don't really want to encourage the creation of another VB developer. - Larry Antram 22 Oct 2002
Hey, at least Logo had, at it's inception, a mechanical turtle. VB has always lacked even that... - Shog9 04-09-2002
Again, you can screw up a C/C++ program just as easily as a VB program. OK, maybe not as easily, but it's certainly doable. - Jamie Nordmeyer - 15-Nov-2002
|
|
|
|
|
thanks for that, but thats what i actually thought of already, but my problem is that the .rc file is completely empty.
i created the dialog from Insert->Resource ( and added what i wanted in it from the floating menu - e.g edit boxes etc.) but it didn't add any code to the .rc file. which as i say is completely blank. 
any ideas??
thanks grahamoj.
|
|
|
|
|
It's a mystery to me how this is possible, sorry. I dunno where else VC would store the dialog box.
Christian
No offense, but I don't really want to encourage the creation of another VB developer. - Larry Antram 22 Oct 2002
Hey, at least Logo had, at it's inception, a mechanical turtle. VB has always lacked even that... - Shog9 04-09-2002
Again, you can screw up a C/C++ program just as easily as a VB program. OK, maybe not as easily, but it's certainly doable. - Jamie Nordmeyer - 15-Nov-2002
|
|
|
|
|
i thought i could extract like a icon or something..
does anyone else know how to extract the actual dialog form??
thanks
grahamoj.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
