wapd@houxj.UUCP (Bill Dietrich) (01/04/84)
Out of pure curiosity : Does anyone know of a language (or compiler, interpreter or assembler) that REQUIRES comments ? To force "good" documentation, sort of ? For example, one might want to require a block comment at the beginning of each function. Or force a comment on every line of assembly language programs (especially useful for an assembly language course). Another twist is to require a comment on every line that is complex, by some measure (numbers of characters, number of operators, bizarre instructions, data in text section, etc). Bill Dietrich houxj!wapd
liz@umcp-cs.UUCP (01/04/84)
Yes, I have heard of a compiler that had forced commenting. I think it was our local PL/1 compiler -- the PLUM compiler (PL/1 Univ of Maryland). It simply required 10% of the lines to be comments or to contain comments. If they didn't, you got some kind of warning message. -Liz Allen -- Univ of Maryland, College Park MD Usenet: ...!seismo!umcp-cs!liz Arpanet: liz%umcp-cs@CSNet-Relay
ken@turtleva.UUCP (Ken Turkowski) (01/05/84)
Cobol is so verbose, it forces comments. [All flames should be sent to /dev/ibm].
mckeeman@wivax.UUCP (01/05/84)
Teaching systems have tried enforcing certain style requirements. I once had a no-paragraph-punisher for PL/I, and a comment counter. The former was quite interesting. Within two weeks, I could have turned it off, NOBODY violated the conventions after that. The comment counter was less successful. What it did was force the student to write comments, so that the grader could evaluate them. It stopped the /* increment i */ kind of comments. My rule was a comment for every procedure, begin and do. What I mainly learned was that no simple rule would do, and spent a lot of time defending the comment counter algorithm, instead of evaluating the quality of the comments. Incidentally, failure to pass the style checks prevented execution... It is my present opinion that a static analyzer, style analyzer should precede compilation, and be passed before compilation is allowed. Thus the program {x=1; x=2} could not be compiled because x is not used after it is set. Fortunately I am not teaching programming right now...
jr@fortune.UUCP (John A. Rogers) (01/06/84)
I used to use an assembler (ASSIST), which had an option to require comments. (ASSIST was written for the IBM 360/370 series, by the University of Pennsylvania, if I remember correctly). You could install the assembler on the system, and define what percentage of the instructions should have non- blank comments. We didn't have it installed with that option, so I don't know how smart it was, and I don't have the documentation any more. I'm not sure that just checking for the existence of comments is very useful... For instance, I've seen code from IBM (e.g. parts of OS, HASP, and an air-traffic control system), where lots of lines have comments, but they tend to be of the form "PTF12345-99"... I.e., whenever they change the code, they "gang-punch" (or whatever) a code number which indicates why the fix was made (where PTF stands for "Program Temporary Fix"). This is a comment, but it's not what I would call a "useful" comment. I'd like to see the PTF number (or whatever), but I'd also like to see DESCRIPTIVE comments, and I don't know how you'd write a program to check for them. I hope this helps... -- John Rogers - CompuServe: 70140,213 - UUCP: fortune!jr - MCI Mail: jrhpp
robison@eosp1.UUCP (Tobias D. Robison) (01/06/84)
I don't know of a compiler or assembler that forces comments, but I'm not sure it would do much good. Haven't you seen comments like these: C Now multiply total times percent: AMOUNT = TOTAL * PERCEN C Check whether switch is nonzero: IF SWITCH .NE. 0 goto 1200 C open the "squmxk" file: ...and so on. Or, my favorite in assembly language comment: ADD R1,R2 ;add register 2 to register 1 Good comments are written by people who know what they are doing and want to do it. - Toby Robison decvax!ittvax!eosp1!robison or: allegra!eosp1!robison (maybe: princeton!eosp1!robison)
phipps@fortune.UUCP (Clay Phipps) (01/06/84)
------------------------------- Expending implementation effort or invoking the wrath of the local standards czar or class instructor to force commenting is a total waste of time. What will be produced for a sequence of code like this j := 0; ... j := (j + 1) mod n; by an unwilling, unconscientious, or misguided commmenter (commentator ?) will be something like this j := 0; {zero out j} ... j := (j + 1) mod n; {add 1 to j} The above only told you WHAT was being done, which you could get from reading the statements without their comments. With an example like that, you'll have a difficult time convincing students, employees, or the neighborhood kid hacker that commentary in programs is important or even useful. The thing that is really needed for these same source statements is some information as to WHY things are being done. If this code were being used to implement a queue, then I would want comments like these j := 0; {select initial element of queue} ... j := (j + 1) mod n; {advance to next element in queue} Now the reader should be able to figure out that the queue is circular. The code itself is not really readable, per se, but the comments above bear the entire burden that should really be shared by judicious selection of symbolic names and appropriate commentary. Anyone who has to maintain or enhance the code is better off with names more like "QElemIndex" and "QElemLimit" than "j" and "n". -- Clay Phipps -- {allegra,amd70,cbosgd,dsd,floyd,harpo,hollywood,hpda,ihnp4, magic,megatest,nsc,oliveb,sri-unix,twg,varian,VisiA,wdl1} !fortune!phipps
tjt@kobold.UUCP (T.J.Teixeira) (01/06/84)
wivax!mckeeman says: Incidentally, failure to pass the style checks prevented execution... ... Fortunately I am not teaching programming right now... Actually, I think it's more fortunate you're not writing the Unix C compiler now! :-> -- Tom Teixeira, Massachusetts Computer Corporation. Westford MA ...!{ihnp4,harpo,decvax,ucbcad,tektronix}!masscomp!tjt (617) 692-6200
smh@mit-eddie.UUCP (Steven M. Haflich) (01/06/84)
A wonderful notion! But how do we convince yacc and lex properly to document generated code and tables? While we're at it, let's have GM build automobiles that *can't* be driven faster than 55 MPH. :-) Seriously, I fuzzily remember from working at IBM in the 60 that there were standards for documentation of assembly code: basically, every code line should bear a comment. Needless to say, such a standard cannot guarantee comments which are useful.
ram@pyuxbb.UUCP (R Allan Muller) (01/09/84)
I find that a printed copy of a program is essential for maintaining large software systems. A visual editor gives a good view of a small portion of a routine; however, it does not show a whole routine at one glance. I believe that programs should be formatted for presentation on paper. Comments can then be placed in line or set off by white space as appropriate. Programs that are formatted for a screen tend to be too compact for my taste; needed documentation is eliminated to allow the program to fit on a screen.
andree@uokvax.UUCP (01/11/84)
#R:houxj:-31900:uokvax:9000016:000:1049 uokvax!andree Jan 9 21:02:00 1984 Yes, I have noticed the problem of screens (and printers) being to narrow/short/SMALL. The solution is not in the hardware (especially printers), nor in the languages, but in the display software. My solution to this problem is to format code for an 80 line printer/terminal (I too use an MX-80 for printing), with blank lines and comments interspersed fairly freely. If something won't fit on the screen, I tend to bend it a little - or better yet, try to reorganize the code. Things work great on printers. Then, to edit the code, I use (semi-)smart software. Editors that will let me split the screen are a *MUST*, so I can look at a structure/define/comment while writing the code that uses it/them. If the definition is in another file, this feature is even more important. Better yet are truly smart editors, that will let me elide pieces of the text. Things like all things nested below level n, or all in-line comments, or all comments, etc. I can chase down further references for anyone that's interested. Or ask in net.cog-eng. <mike
saj@iuvax.UUCP (02/15/84)
#R:houxj:-31900:iuvax:11800009:000:977 iuvax!apratt Jan 8 00:47:00 1984 One thing which has often stymied my attempts at commenting is the fact that screens and printers are 80 columns wide (MX-80s, anyway). With that limitation, deeply nested structures have no room at the end of the line for comments, and no good place to put one (the line above? the line below?). Another limitation is 24-line screens. With most editors, this leaves (at most) 23 lines of the program visible at one time, and for that reason blank lines need to be scarce (especially in complex structures where you want to see as much as possible). On the other hand, complex structures are where blank lines are MOST helpful on a printout, with plenty of blank-line-delimited comments. Which way do you go with it? Depends mostly on the availability of printouts. If they're quick and cheap, use that right margin (and beyond) for all it's worth. Otherwise, program for the screen. Has anybody else noticed this problem? -- Allan Pratt ...ihnp4!iuvax!apratt
decot@cwruecmp.UUCP (Dave Decot) (02/16/84)
If a function or procedure gets too long, or too deeply nested to fit in a screenful, take some of the deeper code and move it to a separate procedure or function. This will leave more room for comments and blank lines, and if the new modules are selected well, makes the program even easier to understand. If a data structure initialization gets too long or complicated to fit on one screen, find some way to modularize it, or read it in from a separate file. Dave Decot "Programmers are people, too." decvax!cwruecmp!decot (Decot.Case@rand-relay)
sdo@u1100a.UUCP (Scott Orshan) (02/17/84)
Putting comments on deeply nested code is only a problem if the comments are on the right. There's no reason the comment can't precede the code. e.g. /* Print "hello world" message */ printf("hello world\n"); Scott Orshan Bell Communications Research Piscataway 201-981-3064 ihnp4!u1100a!sdo
edhall@randvax.ARPA (Ed Hall) (02/18/84)
---------------------------------- I'm a great believer in block comments in front of every procedure definition, and a minimum number of line-by-line comments in the code. I assume that the person reading the code knows the language, and so reserve line comments for `tricky' code only (which I try to avoid). If the algorithm needs explaining, put it in the block comment. If that comment is too long, it's a sure sign the procedure is doing too much, and should be divided into sub-procedures. Forced commenting? The ultimate in silliness. It's quality, not quantity you want. If the code is badly written, commenting doesn't make it any better. -Ed Hall decvax!randvax!edhall (UUCP) edhall@rand-unix (ARPA)
peters@cubsvax.UUCP (02/20/84)
I used to code in APL, whose conciseness has two implications, one "good" and one "bad:" On the good side, since a procedure that would take ten lines in C would take a single line in APL, it was very rare that a procedure was more than a screen (24 lines) long, and most were 5 -10 lines. This made it very easy to look at a whole procedure at once and figure out what it was doing -- hence tending to make prolific commenting less necessary. On the other hand, there was so much in a single line that it was sometimes hard to see what was being done on a very detailed level, which tended to make comments *more* necessary. In most languages the thing to be concerned about is "missing the forest for the trees." In APL, I used to worry more about "missing the trees for the forest." I usually had a few block comment lines at the beginning of a procedure, and more only when necessary, or when the procedure was very long. Then I had a routine which would go through a workspace and print only function headers and comment lines. Printing these out for all the routines in a workspace gave a wonderful synoptic view of what the different functions did. {philabs,cmcl2!rocky2}!cubsvax!peters Peter S. Shenkin Dept of Biol. Sci.; Columbia Univ.; New York, N. Y. 10027; 212-280-5517
jas@druxy.UUCP (ShanklandJA) (02/21/84)
One more semi-pertinent comment on comments: It has been my experience that if you comment in detail the function of each data structure ("data structure" here includes all storage objects, such as scalars, arrays, structures, etc.) and their interactions at the head of the function or module that uses the data structure, two things happen: (1) You are much more likely to write correct code (I have found "bugs" writing out the comment on a data structure before writing a line of code!). (2) Commenting the *statements* becomes almost entirely unnecessary; to a reader who understands the data structures, the actions of virtually all the statements become obvious. Give it a try! Jim Shankland ..!ihnp4!druxy!jas
thomas@utah-gr.UUCP (Spencer W. Thomas) (02/28/84)
My solution to limited terminal width vs comments is to put long comments before the block of code to which they apply. The code block then usually has NO comments, but that's ok, the entire action was explained above. Makes the comment more readable, too. Also forces me to write meaningful comments (no "Increment a" type comments). =Spencer