dan@lclark.UUCP (Dan Revel) (03/28/88)
In article <2921@enea.se> sommar@enea.UUCP(Erland Sommarskog) writes: [ first he is quoting Richard Harter ] >>Also relevant is the fact that I annotate every line, ala assembly language >>code, unless it is too long to fit a comment field in. Normal format is >>a code field of about 40 chars wide and a comment field of about 35 chars >>wide with all comments aligned. As you may imagine, short names are more > >Good habit. You need a lot of discipline to keep them updated. > Mine is about the opposite. I usually put a describing comment in the >procedure header, explaining parameters if their names doesn't say it all. >For local variables I add a describing comment, except the most trivial. > The code itself does only contain comments if I do some special trick. I much prefer the latter style of commenting. A single comment describing what the next block of code is going to do, instead of a comment on every line. Some lines don't deserve comments, and some comments degenerate into stating the obvious ( increment counter, or something like that ). As to the original topic of variable names, I also prefer names that have some meaning ( not just now, to me, but a year from now, and to someone else to fully versed in my arcane knowledge ). I must admit however that I do hate typing all those letters, also, some variables don't deserve meaningful names ( i.e. loop variables, use i and throw it away ). Perhaps the biggest problem is calling it CODE in the first place, who's idea was that anyways? dan ( tektronix!reed!lclark!dan ) "Someday we'll put this place on the map ... " -- = == := |-) ;^)
g-rh@cca.CCA.COM (Richard Harter) (03/29/88)
In article <200@lclark.UUCP> dan@lclark.UUCP (Dan Revel) writes: ... re remarks of mine about commenting every line of code >I much prefer the latter style of commenting. A single comment describing >what the next block of code is going to do, instead of a comment on every >line. Some lines don't deserve comments, and some comments degenerate into >stating the obvious ( increment counter, or something like that ). Commenting every line is not a substitute for commenting blocks of code -- it is a separate and additional type of commenting with a different function. The block prolog describes generally what is going on in the block (block in the sense of a signifigant group of statements). I am not advocating commenting each line as a universal policy; however I will give my experiences and conclusions. The first is that once you have adopted the style, you find yourself becoming quite compulsive about it. The code doesn't 'look right' without annotation. The second is that it 'decryptifies the code'. We have all had the experience of looking at code, whether your own or someone else's and wondering what is going on. The line comment tells you what the author intended that line of code to do. Example: xp = xp->link; /* Fetch next foobaz link */ versus foobaz_instance = foobaz_instance->link; Everyone, I will suppose, will agree that foobaz_instance is a more meaningful name than xp. However the comment tells, to some extent, what the statement is supposed to do. It is also a permanent record of what the statement does, which saves you deciphering the code when you are modifying it. There is a more subtle benefit of commenting every line which is not obvious -- it forces you to explain, at the time that you write it, what you meant the statement to do! -- In the fields of Hell where the grass grows high Are the graves of dreams allowed to die. Richard Harter, SMDS Inc.