billwolf@hubcap.clemson.edu (William Thomas Wolfe,2847,) (02/24/89)
From article <419@serene.UUCP>, by rfarris@serene.UUCP (Rick Farris): >> |Just follow the convention that when code is updated so are the >> |comments. > > Hmm. That's ok when you're working on small projects. I've never > seen it work in real-life when many programmers were involved. I use a tactic which essentially makes comments as inherent a part of the code as possible: I make all package, procedure, function, type, and variable names as descriptive as reasonably possible. Examples: procedure POSITION_AT_LAST_ITEM (SOME_LINKED_LIST); function ELIMINATE_LEADING_AND_TRAILING_SPACES (SOME_STRING); type SERIALIZABILITY_GRAPH; package GENERIC_SIMPLE_DIRECTED_GRAPH; MENU_OPTIONS : MENU_HANDLER.LINKED_LIST; This allows me to essentially eliminate the need for many of the comments that I see in the code of other programmers. It preserves my comment-writing patience for semantic descriptions of procedures, and for those situations in which I'm using sophisticated strategies to make an ADT implementation as fast as I can possibly get it which involve complex reasoning about the state of the ADT structure (and the variables used by the manipulating algorithms). Also, I've learned to type very quickly, through long hard experience. :=) Bill Wolfe, wtwolfe@hubcap.clemson.edu
wbralick@afit-ab.arpa (William A. Bralick) (02/24/89)
In article <4534@hubcap.UUCP> wtwolfe@hubcap.clemson.edu writes: :-) :-) [lots of stuff lost in space (uh, time (uh, space (uh, you know)))] :-) :-) Also, I've learned to type very quickly, through long hard experience. :=) :-) I personally like to abstract data type. I belly-up to the ol' keyboard abstraction and type my data: long or short, integer or real (oops, I can't type real data on my abstract keyboard (it can only handle concepts on the order of aleph-null (due to strong typing))). Regards (from the Time Coast), -- Will Bralick : wbralick@afit-ab.arpa | If we desire to defeat the enemy, Air Force Institute of Technology, | we must proportion our efforts to | his powers of resistance. with disclaimer; use disclaimer; | - Carl von Clauswitz
rfarris@serene.UUCP (Rick Farris) (02/24/89)
In article <4534@hubcap.UUCP> wtwolfe@hubcap.clemson.edu writes: | I use a tactic which essentially makes comments as inherent a part of | the code as possible: I make all package, procedure, function, type, | and variable names as descriptive as reasonably possible. [some examples deleted] Yes, this is the only way I've seen documentation that tended to be maintained with the code. Personally, I'm a proponent of 4th generation reverse engineering tools to do things like structure charts, etc, since they are *never* maintained if it has to be done manually. | Also, I've learned to type very quickly, through long hard experience. :=) As the ADAge goes, "Programs are *written* once, but *read* many times." Rick Farris RF Engineering POB M Del Mar, CA 92014 voice (619) 259-6793 rfarris@serene.cts.com ...!uunet!serene!rfarris serene.UUCP 259-7757
prc@maxim.ERBE.SE (Robert Claeson) (02/25/89)
In article <4534@hubcap.UUCP>, billwolf@hubcap.clemson.edu (William Thomas Wolfe,2847,) writes: > I use a tactic which essentially makes comments as inherent a part > of the code as possible: I make all package, procedure, function, > type, and variable names as descriptive as reasonably possible. > > Examples: > > procedure POSITION_AT_LAST_ITEM (SOME_LINKED_LIST); I used to do that until I heard that the ANSI C standard will state that external identifiers should not be equal in the first six characters. Maybe POSIX says something else. I don't plan to port my code to anything else than POSIX (and maybe PC-DOS, if I have to). I also label each identifier with two to four characters that indentifies a package. For example, the functions in my package for handling double- linked lists in C has functions like "dlst_create_list" and "dlst_next_item". -- Robert Claeson, ERBE DATA AB, P.O. Box 77, S-175 22 Jarfalla, Sweden Tel: +46 (0)758-202 50 Fax: +46 (0)758-197 20 EUnet: rclaeson@ERBE.SE uucp: {uunet,enea}!erbe.se!rclaeson ARPAnet: rclaeson%ERBE.SE@uunet.UU.NET BITNET: rclaeson@ERBE.SE
rickc@pogo.GPID.TEK.COM (Rick Clements) (03/10/89)
In article <2989@uvacs.cs.Virginia.EDU> you write: >In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes: >>What is needed to improve self-documentation are better programming languages. >This is certainly true, but even the "better" programming languages allow for >the inclusion of comments. There will probably always be parts of the >programmer's concept which need to be expressed in an informal way through >comments. I have learned to include comments like "Doing it <this_way> appeared obvious at first but didn't work because of <something>". I hate solving the same problem twice (even if it a year or so later). You can also list what trade offs lead you to solve a problem the way you did. The code can never tell you the why. Telling the person maintaining the code (maybe yourself) why something was done will help them from creating those crash every 5th Tuesday type of bugs. ---- Rick Clements (RickC@pogo.WV.TEK.COM) -- Rick Clements (RickC@pogo.WV.TEK.COM)