djones@megatest.UUCP (Dave Jones) (02/10/89)
There was some discussion about comments recently in comp.lang.c. (Notice the followup-to line. Seems like the most appropriate group. Hope you agree. I'm not too familiar with the group, having just recently subscribed.) I'm not a religious fanatic about it, but in maintaining lots of different code since 1979, I have developed some preferences for what I like in the code I am charged with maintaining, and what I could do without. Here are some remarks that I wrote up for one of the members of my programming team. I hope they will be helpful. .... In my opinion, the most important parts of a program to document are the structure-declarations and the variable-declarations. You document what the fields and variables "mean" in terms of invariants. Use descriptive names in addition to comments, and don't use non-conventional abbreviations. If you do that, and if the code is well structured, documenting an algorithm is usually (but not always) unnecessary. Usually it is obvious how the algorithm will go about the process of reestablishing a broken invariant. Except in unusually tricky cases, the documentation for a procedure should only say WHAT the procedure does, not HOW it does it. If the algorithm is not tricky, the WHAT will make the HOW clear enough. Comments which assert the obvious are just clutter, worse than nothing. Before you put comments into a procedure, ask yourself whether there is some way to make the procedure itself understandable, on its own. Perhaps you can give some variables more descriptive names. Or you might even change the control flow. You may be happily surprised to find that the clearer algorithm is actually better! A good way to sum this up would be to say, document things which would be difficult or impossible for the maintainer to surmise. If something is easy to figure out, don't bother the reader with a comment. If something is hard to figure out, ask yourself whether the complexity is necessary. A comment which is inaccurate is worse than no comment. Thus, comments should be "robust". They should either say things that are likely to remain true over the lifetime of the code, or they should be positioned so that it will be obvious to the maintainer when he invalidates a comment. For this reason, comments should only refer to their immediate surroundings. If a comment says, "The previous four routines do so and so...," a code-maintainer is likely to move one of the routines, or alter one without even knowing that he is "breaking" a comment. The same is true if a comment says, "This routine is called by procA, and procB." The maintainer of procA or procB may not even know about the comment. There are utility programs for generating such cross-reference information directly from the sources, without trusting in comments. Documentation about more general relationships between procedures belongs in a separate design document, or in interface (#include) files. Remember, it is the data-invariants which give purpose to the procedures. Describe the data-invariants where the data structures and variables are declared, typically in #include-files. If you want to make comments to yourself while you are developing or maintaining the code, that's fine. Things like, "When this is integrated, routine foo() will call this routine...", or "I think this probably does so and so." But comments such as these should be marked somehow so that they will be easy to remove later. I have found such comments in code fourteen years old! You don't want to leave them there, so make it easy to remove them later. I usually tag them with my login-name, which I certainly DON'T want to leave in the code! Block comments which are neatly delimited on the right margin may look pretty, but they are hard to modify: /************************/ /* This looks tidy, but */ /* it is hard to main- */ /* tain. */ /************************/ There's another problem with the comment above: It's not one comment; it's several. Utilities which look for comments with certain keywords, etc. will not treat the above as one comment. Here's a good way to go about it: /******************************* * This is one block comment, * and it is easy to modify. ******************************/
rjh@cs.purdue.EDU (Bob Hathaway) (02/11/89)
Dave Jones [djones@megatest.UUCP] Writes: >Here are some remarks that I wrote up for one of the >members of my programming team. I hope they will be >helpful. Thanks, I agree good documentation is invaluable. > >In my opinion, the most important parts of a program to document >are the structure-declarations and the variable-declarations. > This is true, but alternate design strategies can call for an extended perspective on documentation. When using an object oriented design strategy, I'll first write a design document describing the primary objects in the system and their operations. Also in the document will be a high-level description of the important procedures written in an informal PDL, such as a pseudo Ada code. For objects (Adts), first is a description of the object and its rational and system context. For instance, what the object is intended for, why I chose an abstract data object or an abstract data type, and possibly how it will interact in the system, but the last part could go in a separate document as pointed out by Dave Jones. Second is a numbered list of operations and their descriptions. When the entire system is complete, the declarations can be coded in a higher-order language. In Ada, the design is directly implementable as compilable specifications. In Modula or some other language in which the specifications aren't compilable the procedures can be filled in with stubs or empty declarations. The design document can be included as comments and updates to the document and code should be done concurrently. The object descriptions are included in the specifications and optionally in the package or module body, and the (numbered) operation descriptions included for each procedure or method. >Here's a good way to go about it: > >/******************************* > * This is one block comment, > * and it is easy to modify. > ******************************/ > Here's another way: /* * my_procedure * * <ADT design document index> * This is a description of... * ... */ Bob Hathaway rjh@purdue.edu
hughes@math.Berkeley.EDU (eric hughes) (02/11/89)
In article <1813@goofy.megatest.UUCP>, djones@megatest (Dave Jones) writes: >In my opinion, the most important parts of a program to document >are the structure-declarations and the variable-declarations. >You document what the fields and variables "mean" in terms of >invariants. To add to this, I will often explicitly make a comment that a certain variable is "valid," that is, it satisfies all the invariants of its type, as well as ones specific to the variable. Then I am very careful not to use a variable which is not shown to be valid. If part of it is, I'll declare that part valid and use it. This technique has prevented many stupid bugs. > If you do that, and >if the code is well structured, documenting an algorithm is usually >(but not always) unnecessary. Usually it is obvious how the algorithm >will go about the process of reestablishing a broken invariant. I always document an algorithm, not matter how silly. This has helped me avoid what I term "typo bugs," things I meant to do but forgot. > If the algorithm is not tricky, the WHAT >will make the HOW clear enough. Yes, a good statement of the preconditions and postconditions to a function can eliminate most procedural comments. (e.g. now we need to do this, now that.) Rather than use a procedural comment before I do something, I will use an assertion comment about the program state afterwards. This is more useful to me, since it is more detailed and states exactly what just happened, not what I intended it to do. For some reason, I find it easier to objectively look at an assertion than an intention. > Comments which assert >the obvious are just clutter, worse than nothing. I have found that my grasp on the obvious is not what I think it is. :-) My rule of thumb is not to comment anything which is implicit in the syntax of a statement, but I will sometimes comment on the semantics (especially in the case of function calls) and always on the pragmatics (what effect it has). I had a friend once who was taking an assembly language class where the teacher required every program line to be commented. He wrote a filter to translate every instruction into it English equivalent and present it as a comment on that line. LOAD AX, 1 ; load the register AX with the value 1 The teacher was satisfied and the student got good scores on his programs. This is the kind of syntax-based comment I avoid. In a related issue, I have found that program correctness techniques are a good way of documenting code. Not only to they allow you to know that what you are doing is correct, but, more importantly, they are the most concise way of stating exactly what the program does. It is elegant to my mind because it is as simple as possible, but no simpler. Every loop gets both a loop invariant and a bound function in a header before it starts. At the end, the termination conditions are stated explicitly. From that, I separately assert the desired postcondition for the loop. I have found this accurately describes both what the loop does and the outline of how it works. Now I would like some engineering tools with which I could check my correctness proofs, but since none exist (to my knowledge), I have found that conscientious commenting is acceptable. Eric Hughes hughes@math.berkeley.edu ucbvax!math!hughes
perry@apollo.COM (Jim Perry) (02/14/89)
In article <20233@agate.BERKELEY.EDU> hughes@math.Berkeley.EDU (eric hughes) writes: >In article <1813@goofy.megatest.UUCP>, djones@megatest (Dave Jones) writes: > >> Comments which assert >>the obvious are just clutter, worse than nothing. > >I have found that my grasp on the obvious is not what I >think it is. :-) My rule of thumb is not to comment anything >which is implicit in the syntax of a statement, but I will >sometimes comment on the semantics (especially in the case of >function calls) and always on the pragmatics (what effect it >has). > >I had a friend once who was taking an assembly language class >where the teacher required every program line to be commented. >He wrote a filter to translate every instruction into it English >equivalent and present it as a comment on that line. > > LOAD AX, 1 ; load the register AX with the value 1 > >The teacher was satisfied and the student got good scores >on his programs. This is the kind of syntax-based comment I >avoid. > Let me begin by saying that I'm in the camp calling for more comments. Especially in the Unix/C world, the overwhelmingly vast majority of programs are undercommented. It's interesting that some aspects of programming style, e.g. indentation, are fairly consistently applied, while adequate documentation is the remote exception. In your example, the chances are that there is some meaningful piece of information that could have been conveyed -- "start with the first widget" -- rather than restating the language-level semantics. [Did you ever see this friend's filter? I suspect this is an urban myth, as rumors of such "tools" was common (at Dartmouth, and I'm guessing elsewhere) in the mid-to-late '70's.] Consider writing such a filter for C programs. C crams so much stuff into a small area that just expressing what's going on, in English, would generate huge comments. I consider this very fact an argument for the programmer taking the time to construct a pithy description of what a piece of code is intended to do. And I do, by and large, comment every line. Code should be self-documenting, at all levels. The main body of a program should explain what the program does, what the dependencies, files, etc. are, and so on. The data declarations should explain what the data structures are and how they are used. Functions, modules, procedures, macros, etc. should also explain themselves, and so on. This is part of what differentiates engineering from hacking. (The comment-generating program might be the ultimate in hackery, in this context). I would have to say that with the possible exception of some overzealous undergraduate student projects, I've never seen an overdocumented program, and I've seen a vast, vast number of underdocumented ones. I've seen some poorly though verbosely documented ones, as discussed here and elsewhere not all programmers have great communication skills, but never has this been "worse than nothing". -- Jim Perry perry@apollo.com Apollo Computer, Chelmsford MA This particularly rapid unintelligible patter isn't generally heard and if it is it doesn't matter.
dhesi@bsu-cs.UUCP (Rahul Dhesi) (02/14/89)
>>He wrote a filter to translate every [assembly] instruction into English ... >> LOAD AX, 1 ; load the register AX with the value 1 >>This is the kind of syntax-based comment I >>avoid. I come across samples of assembly code for many different machines in books, journals, magazines, source listings, etc., and it is not always easy for me to understand them. If each instruction were accompanied by an English comment, life would be much simpler for all of us. -- Rahul Dhesi UUCP: <backbones>!{iuvax,pur-ee}!bsu-cs!dhesi ARPA: bsu-cs!dhesi@iuvax.cs.indiana.edu
hughes@math.Berkeley.EDU (eric hughes) (02/14/89)
In article <20233@agate.BERKELEY.EDU> I write: >>I had a friend once who was taking an assembly language class >>where the teacher required every program line to be commented. [story deleted] In article <4173bd76.183dc@apollo.COM>, perry@apollo (Jim Perry) writes: >[Did you ever see this friend's filter? I suspect this is an urban >myth, as rumors of such "tools" was common (at Dartmouth, and I'm >guessing elsewhere) in the mid-to-late '70's.] I am almost sure it is not. I have a particular friend in mind, who know works in Boston. As I recall, he wrote it for an IBM-PC for MASM code and the filter was implemented in SNOBOL, a string processing language. I may be mistaken. I will call him up and find out for sure. Eric Hughes hughes@math.berkeley.edu ucbvax!math!hughes
nevin1@ihlpb.ATT.COM (Liber) (02/16/89)
In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes: >Let me begin by saying that I'm in the camp calling for more comments. I'm not. I do agree with you on the problem (poor documentation), but I do not think that more comments is the answer. >Especially in the Unix/C world, the overwhelmingly vast majority of >programs are undercommented. It's interesting that some aspects of >programming style, e.g. indentation, are fairly consistently applied, >while adequate documentation is the remote exception. The question is: Why? From my point of view, good documentation in the form of comments is rare because there is NO WAY of guaranteeing that they are correct with respect to the code. They are a nightmare to maintain, and no one ever has the time to fix the comments when the code has fatal bugs. Also, no one wants to take the time to rewrite their code into English; it's a boring, tedious job, and when it comes down to it only the code really matters to those buying your software. It is human nature to take the path of least resistance; comments go against this path. With very few exceptions, for better or for worse, this is the way of the world. Will requiring Joe Programmer to write more comments fix the situation? No. Joe Programmer will find a way to keep his comment writing to a minimum, even if the code or organization of modules has to suffer for it. >C crams so much stuff into >a small area that just expressing what's going on, in English, would >generate huge comments. I consider this very fact an argument for the >programmer taking the time to construct a pithy description of what a piece >of code is intended to do. And I do, by and large, comment every line. Suppose you require Joe Programmer to comment every line of his C code. What does Joe Programmer do? He writes: (void)strcpy(string0, string1); (void)strcat(string2, string3); (void)strcat(string0, string2); as (void)strcat(strcpy(string1, string0), strcat(string2, string3)); because he only has to comment one line instead of three. The code is less readable in case 2, but Joe Programmer has achieved your goal (a comment on every line) with less effort. (Note: the opposite problem is true when you are measuring number of lines of code as a quality measure: Joe Programmer might rewrite line one of the first case as ( void ) strcpy ( string0 , string1 ) ; and make a tenfold improvement in his statistics!) Here are some real-world examples of what happens when you force a programmer to write lots of comments: Requirement: require file comments in each source file. What Happens: Many functions are stuffed into a single source file, irregardless of whether the functions are related or not. Requirement: require block comments for each function declaration. What Happens: Functions become less modular. In C, a programmer might stuff five functions into one by using a giant case statement. Requirement: always provide a list of what a given function calls and is called by. What Happens: These comments are out of sync very fast. This kind of documentation is much better handled by a software tool than by a programmer. Unfortunately, I have seen the What Happens all too often. Forcing programmers to write more comments is not the answer. What is? >Code should be self-documenting, at all levels. The main body of a program >should explain what the program does, what the dependencies, files, etc. >are, and so on. The data declarations should explain what the data >structures are and how they are used. Functions, modules, procedures, >macros, etc. should also explain themselves, and so on. This is the solution: code should be self-documenting. But, self-documenting is not the same as commenting! When I change a line of code, my documentation should reflect that change automagically. I don't get this with comments, and because of it, the only comments I rely on are my own personal ones. What is needed to improve self-documentation are better programming languages. This is one of the reasons that, for example, C++ is better than C; the resulting code is more self-documenting. The language has to make it easier for me to abstract and be more self-documenting than not; this is the key to solving the problem. The ultimate programming language(tm :-)) will be one where I will never have to write a single comment; it should be clear, concise, and obvious from the code my intentions of what I was programming. We need to improve our programming languages, not increase the quantity of our commenting. >I've seen some >poorly though verbosely documented ones, as discussed here and elsewhere >not all programmers have great communication skills, but never has this >been "worse than nothing". There are many instances on where poorly documented code is "worse than nothing"; most notably, when the comments are WRONG! It has happened too many times that someone reads the comments on how the routine is "supposed to" work, makes a change, and finds out that the implementation is totally different than the comments. I wonder how many lost man-years in software maintenance can be attributed to this. -- _ __ NEVIN ":-)" LIBER nevin1@ihlpb.ATT.COM (312) 979-4751 IH 4F-410 ' ) ) "I will not be pushed, filed, stamped, indexed, / / _ , __o ____ briefed, debriefed or numbered! My life is my own!" / (_</_\/ <__/ / <_ As far as I know, these are NOT the opinions of AT&T.
garison@mirror.UUCP (Gary Piatt) (02/16/89)
>Forcing programmers to write more comments is not the answer. What >is? The solution is to give these programmers their own code after four or five years, and have them modify it (Note: MODIFY, not RECREATE). In one of my former lives (in 1984), I was called upon to change the terminal emulation software I had written to allow it to access multiple display pages. I had done this four years prior to that day, and decided to save myself a day's work by resurrecting the older code and modifying it to fit the new environment. Well, it didn't work that way. The comments on the old code were what you would refer to as "sparse" ("This loads the new page" at the head of twenty lines of code). Instead of saving time, I ended up wasting time; it took me the entire day to understand what I had written only four years before. No matter how good a programmer you are, or how long you've been in the business, you can't expect yourself to remember the intent of every line of code you've ever written. These days, I comment (almost) every line, and WHEN I CHANGE THE CODE, I CHANGE THE COMMENT. When I'm done with the program, and I know that it works, I take the time to add headers to each function, describing what it does and how it works. This method has paid off. Last year the company I worked for in 1984 called me back as a consultant to fix an obscure little bug they had discovered in the software I had written that year. I quoted them a price (and they paid me) for the entire day, but -- because of those comment -- the job only took two hours. -garison- ...good comments are like good sex: too much is never enough
EGNILGES@pucc.Princeton.EDU (Ed Nilges) (02/17/89)
In article <9606@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes: >I'm not. I do agree with you on the problem (poor documentation), but >I do not think that more comments is the answer. The answer is not "more comments", you're right. The answer is "more programs with better written, more accurate comments; and maintenance programmers with more time to update the code as well as the comments." > >The question is: Why? From my point of view, good documentation in >the form of comments is rare because there is NO WAY of guaranteeing >that they are correct with respect to the code. They are a nightmare >to maintain, and no one ever has the time to fix the comments when the >code has fatal bugs. Also, no one wants to take the time to rewrite >their code into English; it's a boring, tedious job, and when it comes >down to it only the code really matters to those buying your software. >It is human nature to take the path of least resistance; comments go >against this path. With very few exceptions, for better or for worse, >this is the way of the world. There is also NO WAY of ensuring that the code itself is correct, period. Does this mean we should not write code? Of course not. In my 17-odd years of experience, much of it spent maintaining other people's code, I have never been misled by a comment. I have, on the other hand, wasted time where a comment would have shown me the way. In "no one wants to take the time" you are referring to people who like to code before they decide, and WRITE DOWN, what their code shall do. It's my humble opinion that these people shouldn't code. Previous posters to this thread have emphasized that the best comments are written prior to code and state the purpose of what shall be coded. > >Will requiring Joe Programmer to write more comments fix the situation? >No. Joe Programmer will find a way to keep his comment writing to a >minimum, even if the code or organization of modules has to suffer for >it. I'd hate to work for someone with such a low opinion of programmers. > > >Suppose you require Joe Programmer to comment every line of his C code. Nobody requires programmers to comment C code. The "every line commented" is a standard for assembly language. C programs require instead function purpose statements, placed at the beginning of each function. > >Here are some real-world examples of what happens when you force a >programmer to write lots of comments: > These examples describe the behavior of people who should not be trusted to program computers. I do agree that software tools can be used to help keep code and documentation up to date; for example, I am currently developing a lot of EXECs for VM/CMS, and I write the initial "METAEXEC" using Script, both to format the descriptive comments and as a macroprocessor for executable code. Since the text formatting commands have access to the same SET symbols as does the EXEC code, I can change the value of a SET symbol and have the code and comment change at the same time: .se maxwords = 1500 . . . /* This software can process at most &maxwords words... . . . IF inwords > &maxwords then SAY "Too many words" However, it is the maintenance programmer's job to update docu- mentation as well as code. > >What is needed to improve self-documentation are better programming >languages. This is one of the reasons that, for example, C++ is better >than C; the resulting code is more self-documenting. The language has >to make it easier for me to abstract and be more self-documenting than >not; this is the key to solving the problem. The ultimate programming >language(tm :-)) will be one where I will never have to write a single >comment; it should be clear, concise, and obvious from the code my >intentions of what I was programming. We need to improve our >programming languages, not increase the quantity of our commenting. But the best comments are statements of purpose, and the Ultimate Programming Language shall not decide for us what use shall be made of it! Also, remember us mortals, who must sputter along in FORTRAN and C... Edward Nilges "Where is the wisdom we lost in knowledge? Where is the knowledge we lost in information?" - T. S. Eliot
peter@ficc.uu.net (Peter da Silva) (02/17/89)
In article <9606@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes: > The ultimate programming > language(tm :-)) will be one where I will never have to write a single > comment; it should be clear, concise, and obvious from the code my > intentions of what I was programming. We need to improve our > programming languages, not increase the quantity of our commenting. I think this is an unreachable goal. If this was possible, we'd not have any lawyers. Everyone would know the intent of any document, law, etc.... It would be obvious from the Constitution whether personal assault rifles are a good idea (and if you think they are, consider personal nerve gas or personal nukes). -- Peter da Silva, Xenix Support, Ferranti International Controls Corporation. Work: uunet.uu.net!ficc!peter, peter@ficc.uu.net, +1 713 274 5180. `-_-' Home: bigtex!texbell!sugar!peter, peter@sugar.uu.net. 'U` People have opinions. Companies have policy. And typos are my own business.
lewis@sigsun.cad.mcc.com (Dave Lewis) (02/17/89)
Here's my comments on your comments about comments! >In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes: > >>Especially in the Unix/C world, the overwhelmingly vast majority of >>programs are undercommented. It's interesting that some aspects of >>programming style, e.g. indentation, are fairly consistently applied, >>while adequate documentation is the remote exception. WHY is indentation almost universally used? Because the payback to the programmer is immediate and effective! Why is adequate documentation a remote exception? I don't think that it's a question of correctness, although this is a demotivating factor. Rather, I think that the typical comment does not convey any useful information to the programmer later. Indentation does, so it gets done. > >The question is: Why? From my point of view, good documentation in >the form of comments is rare because there is NO WAY of guaranteeing >that they are correct with respect to the code. They are a nightmare It's all relative; there is no way to guarantee that the program won't throw up on you the very next time you run it! If there is no possible way to verify correctness of the comments, then the code is not understandable, can not be modified, and must be retired as soon as anything serious happens to it. This is an extreem view, and of course in practice it's very tedious to verify comments... >to maintain, and no one ever has the time to fix the comments when the >code has fatal bugs. Most comments that I have seen don't document the fact that a program has a fatal bug. In fact, usually they state what should be happening, but the reality is that something happened that the code was not designed for. Most times, simply stating what the problem was, and the reasoning behind the method of the fix is the appropriate action. >Also, no one wants to take the time to rewrite >their code into English; I agree, this is useless - the code already states what it's doing! AND I think that this is a perfect example of why comments are not useful to programmers - as written they don't add any information to the program. It's only when you come back the next year that you have the proper perspective on what comments should have been there! >it's a boring, tedious job, and when it comes >down to it only the code really matters to those buying your software. >It is human nature to take the path of least resistance; comments go >against this path. With very few exceptions, for better or for worse, >this is the way of the world. ...the path of least resistance... Agreed. The trick is that the comments should greatly lower the resistance the next time you look at the code. Certaintly, indentation does! lots of stuff about programmers getting around various requirements deleted. >There are many instances on where poorly documented code is "worse than >nothing"; most notably, when the comments are WRONG! It has happened >too many times that someone reads the comments on how the routine is >"supposed to" work, makes a change, and finds out that the >implementation is totally different than the comments. I wonder how >many lost man-years in software maintenance can be attributed to this. Not too much... most maintainers will verify comments if they can. What's the alternative? The alternative is to spend an enormous amount of time analzying what the code is doing, and knowing that, theorizing about why it's doing it that way, and what the trade-offs were when the data structures were designed, whether it was done that way for efficiency, or was it just the easiest way to do it? This alternative is what consumes the most time in software maintenance. The NECESSITY to do this is virtually what DEFINES the nature of the work as maintenance! If you didn't need to do this, it is either a very rare program, trivial, or you are still in the initial development phase. Sorry this was so long... Dave Lewis @ MCC CAD Program [512] 338-3663 | ARPA: lewis@mcc.com UUCP: {uunet,harvard,gatech,pyramid}!cs.utexas.edu!milano!cadillac!lewis
vfm6066@dsacg3.UUCP (John A. Ebersold) (02/17/89)
My observations. IMHO comments should document: Why a particular data structure is being used. Why that *seemingly* silly bit of code was written. You know, the code your read and a say to yourself. "This is stupid. It doesn't need to be done this way. I'll change it." GOTCHA. Comments should documents side effect created or depended on - I know, a bad idea but it happens. Module comments should give the big picture. Comments should NOT restate the syntax. Programmer who write comments like: /* ** See if you can figure this out. Ha. */ should be condemmed to writing an operating system in BASIC without using GOSUB. We see the frenzied Maintainence Programmer grabbing shirt of the perpetrator of the above comment and hear the sound of their hand knocking sense into the errant comment writer. Smeck, smeck, smeck, smeck, smeck. The right way to write a comment :-) : I once wrote a twenty line comment to document on interrupt handler, its expected data arrival rate, how it could be blown out of the water and why it probably would not happen. The interrupt handler was less than ten lines of C code. -- Speaking for myself: John A. Ebersold, Unify Corporation @ Defense System Automation Center osu-cis!dsacg1!dsacg3!vfm6066 Columbus, Ohio 1-614-238-5923 AV-850 5923 Systems with poorly understood requirements cannot be developed in a crunch.
rjh@cs.purdue.EDU (Bob Hathaway) (02/18/89)
> Also, no one wants to take the time to rewrite >their code into English; it's a boring, tedious job, and when it comes This seems to go backwards. Programmers should first design their software then implement it. You seem to be advocating implementation then design. The descriptive algorithm should come first, then the code. If the algorithm can be coded in a truly self descriptive form no comments will be necessary but in instances where the design and implementation are not the same, comments help. >Will requiring Joe Programmer to write more comments fix the situation? >No. Joe Programmer will find a way to keep his comment writing to a >minimum, even if the code or organization of modules has to suffer for >it. True, but requiring Joe Programmer to design his software first will help, and the design can be included in the comments. >This is the solution: code should be self-documenting. But, >self-documenting is not the same as commenting! When I change a line >of code, my documentation should reflect that change automagically. I >don't get this with comments, and because of it, the only comments I >rely on are my own personal ones. I've always believed in self-documenting code and used this excuse to avoid commenting until I graded a systems programming course about a year ago. The programs which had long procedures, few comments, and weren't self documenting (*to me* at least) were the worst. Trying to work with these programs in a professional environment would have been a nightmare. The self-documented programs which kept their procedures small and abstracted a single function were by far the best but comments were still necessary. Uncommented programs take several times longer to read and understand than commented ones. After my experience grading and after working with several large programs my conclusion is that well commented, self-documenting code is by far the best. Also, forcing an a-priori design and including this design in comments will not only produce higher quality and better designed programs but programs which are more easily understood since the structure of the software is documented. >intentions of what I was programming. We need to improve our >programming languages, not increase the quantity of our commenting. I agree entirely and advocate languages which allow direct expression of algorithms and design. But since current languages are approaching that point and are not yet there, commenting is still necessary. >There are many instances on where poorly documented code is "worse than >nothing"; most notably, when the comments are WRONG! It has happened >too many times that someone reads the comments on how the routine is >"supposed to" work, makes a change, and finds out that the >implementation is totally different than the comments. I wonder how >many lost man-years in software maintenance can be attributed to this. I think the poorly designed, poorly documented systems have caused most of the trouble, not out-of-date commenting. Just follow the convention that when code is updated so are the comments. The benefits of a well commented design far outweigh the costs. Well documented code is easy to understand and modifications to the software can be done in terms of the higher-level design. Since the design is directly implemented in the code, corresponding changes should be easy. Bob Hathaway rjh@purdue.edu
shf@well.UUCP (Stuart H. Ferguson) (02/20/89)
+--- From: nevin1@ihlpb.ATT.COM (Liber) | I do agree with you on the problem (poor documentation), but | I do not think that more comments is the answer. Perhaps it's quality that matters, not quantity. | [...] only the code really matters to those buying your software. That may have been true in "the old days," but people expect a lot more than mere functionality from modern software. People are buying not just the program, but "support," which means documentation, bug fixes and updates. All of this is easier with well commented code. | It is human nature to take the path of least resistance; comments go | against this path. I used to think this too. I started, in "the old days," writing machine code directly into core memory. There was no such thing as source. Comments were a list of addresses and what they contained kept in a pile of ragged sheets of loose yellow paper. A "patch" was a jump to a free section of memory to execute new code which then jumped back. The heart of the matter -- what the customer paid for -- was the raw code, the stream of machine instructions that WERE the program. The "comments" were auxiliary, for my use only. (We still have a piece code like that, and the only person who can do anything useful with it is the original programmer. I fear he may be wedded to that program for the rest of his life...) As time passed and I matured as a programmer, however, my opinion of the role of "code" and "comments" reversed. I think I would now be happier with a language that was all comments, with tokens to delimit code, rather than the other way around. Code is only understandable in a context. For the 'C' language, for example, K & R, or some other 'C' reference work, provides the background for understanding a usage of the notation. The fragment, for (i=0; i<N; i++) means nothing outside the context provided by the "commenting" of the language semantics. Likewise, the comments for a particular program can establish the role of such a construct within the overall context of the design. It's a little like mathematics. Despite how advanced and really sophisticated mathematical notation has become over the centuries, all math textbooks consist of some limited number formal statements of theorems as required, surrounded by a lot of discussion which places the theorems in a context with the rest of math. The discussion -- the "comments" -- are at least as much of the math as the formal expressions. There wouldn't be math without the formalisms, but there also wouldn't be math without the stated context. Both are essential. | This is the solution: code should be self-documenting. But, | self-documenting is not the same as commenting! [...] | What is needed to improve self-documentation are better programming | languages. This is one of the reasons that, for example, C++ is better | than C; the resulting code is more self-documenting. The language has | to make it easier for me to abstract and be more self-documenting than | not; this is the key to solving the problem. Again, no programming language is "self documenting." For a formal domains like 'C' or 'C++', the context is provided by the reference works on the language which set forth the "philosophy" of the domain as well as the formalisms. Without that context, the code is just so much jibberish. When we write programs, we are creating a new domain consisting of new objects (data structures) and new operations (functions or subroutines). Like other formal constructs such as programming languages and mathematical derivations, the meaning cannot be implied without some background. We need to provide the context, to describe the underlying design, which allows other people to navigate in the worlds we create. | The ultimate programming language(tm :-)) will be one where I will | never have to write a single comment; it should be clear, concise, | and obvious from the code my intentions of what I was programming. I think "comments" are not something separate from the code but are rather an integral aspect of any design. My UPL (since we're engaging in fantasy :-) would be a combination of conventional programing and hypertext -- a kind of Hyper-Programming (tm). The program itself would appear as a mixture of graphs, block diagrams, pseudocode and straight prose. I might create a graphical icon for a data structure that would appear in the flow diagram for an algorithm, and I could expand this icon to show its formal description with some prose describing its purpose and a display showing how the data structure can be used. Part of this display might be generated by the programming language by scanning how the data structure is actually used, and part of it might have been entered by a programmer in specifying contraints on its use. If I encounter a function I don't understand, I might first pop up a window containing an English description of the function and its purpose. Then, if I need more, I might look deeper and find a piece of pseudocode which I could explode and find a formal specification of the code in a kind of block diagram, each piece of which could be similarly expanded. I could also easily find all the places where this function is used by following links backwards. Note that this doesn't abolish comments; if anything it makes them foremost. | NEVIN ":-)" LIBER nevin1@ihlpb.ATT.COM (312) 979-4751 IH 4F-410 -- Stuart Ferguson (shf@well.UUCP) Action by HAVOC
ssdken@jarthur.Claremont.EDU (Ken Nelson) (02/22/89)
In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes: >The question is: Why? From my point of view, good documentation in >the form of comments is rare because there is NO WAY of guaranteeing >that they are correct with respect to the code. They are a nightmare >to maintain, and no one ever has the time to fix the comments when the >code has fatal bugs. Also, no one wants to take the time to rewrite >their code into English; it's a boring, tedious job, and when it comes >down to it only the code really matters to those buying your software. >It is human nature to take the path of least resistance; comments go >against this path. With very few exceptions, for better or for worse, >this is the way of the world. Right, it is human nature. However there is a way of ensuring good documentation of C or any code. The technique is called the "review". An independant revview both of the code and the comments, and a software managers insistence on fixing problems identified in the reviews, will ensure proper documentation, and also raise the quality of the software product. All it takes is devoting a little up-front effort which will yield large returns in the future as program complexity increases, and as staff turnover makes orignial authors unavailable. The reason "no one" wants to take the time to do it right is that "no one's" team leader or manager did not require, enforce and provide incentives for good documentation. The problem is a people problem, not one of programming language, although certain languages do lend themselves to better documentation. Software analysis tools can help by automating much of the header information that becomes out of date (calls, called-by, change notices etc...). Tools are not a panacea, but merely a means of complementing a vigorous and strictly enforced documentation program that is based on people doing their job correctly. Ken Nelson Principal Engineer Software Systems Design (714) 624-2306 In this case the views expressed above are shared by my employer.
perry@apollo.COM (Jim Perry) (02/22/89)
In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes: >In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes: > >>Let me begin by saying that I'm in the camp calling for more comments. > >I'm not. I do agree with you on the problem (poor documentation), but >I do not think that more comments is the answer. > >>Especially in the Unix/C world, the overwhelmingly vast majority of >>programs are undercommented. It's interesting that some aspects of >>programming style, e.g. indentation, are fairly consistently applied, >>while adequate documentation is the remote exception. > >The question is: Why? From my point of view, good documentation in >the form of comments is rare because there is NO WAY of guaranteeing >that they are correct with respect to the code. They are a nightmare >to maintain, and no one ever has the time to fix the comments when the >code has fatal bugs. Also, no one wants to take the time to rewrite >their code into English; it's a boring, tedious job, and when it comes >down to it only the code really matters to those buying your software. >It is human nature to take the path of least resistance; comments go >against this path. With very few exceptions, for better or for worse, >this is the way of the world. > >Will requiring Joe Programmer to write more comments fix the situation? >No. (examples of how Joe Programmer sleazes his way out of writing comments). This attitude is one of the best arguments I've seen for distinguishing Software Engineering from Programming. Jane Engineer writes comments not because someone is requiring her to, but because she knows that this code is going to be around for a long time, and that the initial writing is a tiny fraction of its lifetime. Jane Engineer's had the pleasure of trying to modify a piece of Joe Programmer's undocumented code, and doesn't want the next person to work on her code use words like that about *her*. For that matter, there's every chance that next person will be Jane herself two years from now. Joe's now selling shoes in Peoria, by the way. "Rewrite their code into English" shows a basic misunderstanding. Code expresses some underlying algorithm which you should have thoroughly thought through before rendering it in C. Your comments should be a parallel rendering into English. If anything, you should write comments *first*. Proper documentation naturally complements the code. While it's true that there's no way of guaranteeing that comments agree with the code, the reverse is equally true. If the comments are a good English synopsis of the desired intent of the function, and the code doesn't agree, there's every chance that the code is wrong. If Joe Programmer hacks up Jane Engineer's code without updating the comments, confusion can arise, but that's a worst-case scenario that's never bitten me badly. >This is the solution: code should be self-documenting. But, >self-documenting is not the same as commenting! When I change a line >of code, my documentation should reflect that change automagically. I >don't get this with comments, and because of it, the only comments I >rely on are my own personal ones. > >What is needed to improve self-documentation are better programming >languages. As you point out earlier, this is the Real World. Some bright sunny day we might have such languages, but the fact is we're stuck with C for quite some time now, and C is more self-obfuscating that self-documenting; the comments are all you've got. -- Jim Perry perry@apollo.com Apollo Computer, Chelmsford MA This particularly rapid unintelligible patter isn't generally heard and if it is it doesn't matter.
nevin1@ihlpb.ATT.COM (Liber) (02/22/89)
In article <6066@medusa.cs.purdue.edu> rjh@cs.purdue.edu (Bob Hathaway) writes: |This seems to go backwards. Programmers should first design |their software then implement it. You seem to be advocating |implementation then design. The descriptive algorithm should |come first, then the code. I have a problem with Top-Down programming (design then implementation); it happens to be the same problem I have with Bottom-Up programming (implementation then design). You so eloquently point it out in your next sentence: |If the algorithm can be coded in a |truly self descriptive form no comments will be necessary but in |instances where the design and implementation are not the same, |comments help. But design and implementation should not differ! If this is happening, one of the two is wrong! In the case of Top-Down, I would guess that it is probably the design that is wrong; something wasn't taken into account until someone actually tried to implement the design. The problem with Top-Down (and Bottom-Up) programming is that there is no feedback mechanism. What happens when an implementation discovers a bug in a design? Does it happen that people go back and formally re-review an already approved design document? Not nearly as often as it should, I suspect. Or at least go back and change the design to match the implementation? It gets even worse when there are many levels to the design. There needs to be a feedback loop. |True, but requiring Joe Programmer to design his software first will help, |and the design can be included in the comments. Yes, but until we have good hypertext systems that will allow Joe Programmer to do this easily and painlessly, he basically has to maintain TWO design documents, and when a human being has to do it, it tends to get out of sync, and eventually useless. |After my experience |grading and after working with several large programs my conclusion is that |well commented, self-documenting code is by far the best. Also, forcing |an a-priori design and including this design in comments will not only |produce higher quality and better designed programs but programs which are |more easily understood since the structure of the software is documented. I agree. And the only way I see this happening is by making this easier than the other, lazier alternatives. |I agree entirely and advocate languages which allow direct expression of |algorithms and design. But since current languages are approaching that |point and are not yet there, commenting is still necessary. No argument here. |I think the poorly designed, poorly documented systems have caused most |of the trouble, not out-of-date commenting. Just follow the convention |that when code is updated so are the comments. The benefits of a well |commented design far outweigh the costs. Well documented code is easy |to understand and modifications to the software can be done in terms of |the higher-level design. Since the design is directly implemented in the |code, corresponding changes should be easy. The real question is: what can we do to make this happen? -- _ __ NEVIN ":-)" LIBER nevin1@ihlpb.ATT.COM (312) 979-4751 IH 4F-410 ' ) ) "I will not be pushed, filed, stamped, indexed, / / _ , __o ____ briefed, debriefed or numbered! My life is my own!" / (_</_\/ <__/ / <_ As far as I know, these are NOT the opinions of AT&T.
hsd@uvacs.cs.Virginia.EDU (Harry S. Delugach) (02/22/89)
In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes: > From my point of view, good documentation in >the form of comments is rare because there is NO WAY of guaranteeing >that they are correct with respect to the code. They are a nightmare >to maintain, and no one ever has the time to fix the comments when the >code has fatal bugs. Also, no one wants to take the time to rewrite >their code into English; it's a boring, tedious job, and when it comes >down to it only the code really matters to those buying your software. What about the customer who wants to know why a certain multi-million dollar company is taking so long to fix a reported bug in their software? What about the teams of programmers who are trying to understand each other's code in order to get the product out the door? >It is human nature to take the path of least resistance; comments go >against this path. With very few exceptions, for better or for worse, >this is the way of the world. I think the only way to get programmers to document their code is to convince them that they gain tangible benefits from including comments in their code. Sometimes it means having a programmer go back to a year-old program and try to make efficient changes to it. Sometimes it means getting livid with anger at the long-gone programmer when you have to maintain his/her uncommented code (Do unto others...). No one should include comments because they're supposed to, or (egad!) required to. They should do it, in the words of the TV commercial, because it's the right thing to do, like throwing your trash in the trash can instead of littering. >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. >There are many instances on where poorly documented code is "worse than >nothing"; most notably, when the comments are WRONG! It has happened >too many times that someone reads the comments on how the routine is >"supposed to" work, makes a change, and finds out that the >implementation is totally different than the comments. I wonder how >many lost man-years in software maintenance can be attributed to this. Probably about the same number of person-hours taken up in going to and from coffee machines in a million software developers' offices. :-) Seriously, whenever I maintain code with such comments, I make a note to the effect that the comments may be invalid. Sometimes, I just delete them entirely, so I guess I agree that poor comments are worse than none. Clearly the best thing is to add new comments when you make a change. -- Harry S. Delugach Dept. of Computer Science, Univ. of Virginia, Charlottesville, VA 22901 U.S.A. INTERNET: hsd@cs.virginia.edu BITNET: hsd2x@virginia UUCP: ..!uunet!virginia!uvacs!hsd CIS: 72727,2363
EGNILGES@pucc.Princeton.EDU (Ed Nilges) (02/23/89)
In article <419ca3bc.183dc@apollo.COM>, perry@apollo.COM (Jim Perry) writes: > >(examples of how Joe Programmer sleazes his way out of writing comments). > >This attitude is one of the best arguments I've seen for distinguishing >Software Engineering from Programming. Jane Engineer writes comments not >because someone is requiring her to, but because she knows that this >code is going to be around for a long time, and that the initial writing >is a tiny fraction of its lifetime. While I am in favor of highly literate, complete, and well- written comments, this posting places the blame for undercommented software on individual shoulders. Far more important is the attitude of management. In some situations, heavy use of "design methodologies" prior to coding have left little time for programmers to do other than crank out uncommented code. In others, management pressure for visible results selects out those programmers who neglect comments. Also, whether one is a programmer versus a software engineer is not a matter of personal virtue. Traditional engineers were backed-up by legal, educational, and certification requirements, none of which apply to our field. It is dangerous to allow management alone to define who is an engineer. Finally, I'd appreciate talking to a good programmer over a person who (in the absence of legal/educational/certification requirements) pretends to be a "software engineer". Edward Nilges ALLE MENSCHEN WERDEN BRUDER - Schiller
rjh@cs.purdue.EDU (Bob Hathaway) (02/23/89)
(I write) >|This seems to go backwards. Programmers should first design >|their software then implement it. You seem to be advocating >|implementation then design. The descriptive algorithm should >|come first, then the code. In article <9689@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes: >I have a problem with Top-Down programming (design then >implementation); it happens to be the same problem I have with >Bottom-Up programming (implementation then design). You so eloquently >point it out in your next sentence: Design then implementation is not necessarily top-down programming. First some terminology. Top-down design involves a functional view starting at the top and working its way down. Top-down implementation is a programming methodology which begins coding (implementing the design) at the top level procedures. Bottom-up design also involves a functional (procedural) view but starts design with the bottom level procedures and bottom-up implementation begins coding with the bottom level procedures. For the past several years (since my first program) I began with an Adt, or more object oriented approach to design and implementation. I would study the problem and form an informal solution and identify the Adts (objects in the system). The informal solution would be in a high level pseudo-code and was usually top-down for the main program and within modules. This provided a modular design with abstract data types. It could also be categorized as a top down design with the data structures and functionally related subprogram units encapsulated within modules. The Adts provided an excellent starting point for coding. They could be separately tested and frequently the driver program for these tests was most conveniently the original program and after "testing" my Adts the program was finished. The fact that I was often done weeks early attested to the techniques success. The informal pseudo-code is refined into working code but since pseudo-code usually offers a more informal description of an algorithm than working code, it is easier to understand. >|If the algorithm can be coded in a >|truly self descriptive form no comments will be necessary but in >|instances where the design and implementation are not the same, >|comments help. >But design and implementation should not differ! If this is happening, >one of the two is wrong! In the case of Top-Down, I would guess that >it is probably the design that is wrong; something wasn't taken into >account until someone actually tried to implement the design. The I disagree. Pseudo-code is much easier to read than programming code. Comments reflect algorithms in an informal way that is more understandable than programming code. They are semantically equivalent, but if I think an informal description is easier to read, I'll provide it (you can put me in the conscientious category of programmer who is always trying to write better software). When an algorithm can be directly expressed in code (ie. just add underscores) as is often the case, comments aren't necessary. >problem with Top-Down (and Bottom-Up) programming is that there is no >feedback mechanism. What happens when an implementation discovers a >bug in a design? Does it happen that people go back and formally >re-review an already approved design document? Not nearly as often as >it should, I suspect. Or at least go back and change the design to >match the implementation? It gets even worse when there are many >levels to the design. There needs to be a feedback loop. Any conscientious programmer will update the appropriate documents. But if put on a system where the comments are in doubt, I can always ignore them. When working with large C programs, I often waste a lot of time trying to understand undocumented field declarations and incomplete function descriptions. A correct comment would save time and it should be obvious from the code if a comment isn't accurate. As suggested in an earlier article, large software projects with elaborate standards can hold design and code reviews to insure correctness. >|True, but requiring Joe Programmer to design his software first will help, >|and the design can be included in the comments. >Yes, but until we have good hypertext systems that will allow Joe >Programmer to do this easily and painlessly, he basically has to >maintain TWO design documents, and when a human being has to do it, it >tends to get out of sync, and eventually useless. Yes, thats why there are software development environments and APSE's and why I keep asking for them:-) |I think the poorly designed, poorly documented systems have caused most |of the trouble, not out-of-date commenting. Just follow the convention |that when code is updated so are the comments. The benefits of a well |commented design far outweigh the costs. Well documented code is easy |to understand and modifications to the software can be done in terms of |the higher-level design. Since the design is directly implemented in the |code, corresponding changes should be easy. > The real question is: what can we do to make this happen? Be conscientious! Bob Hathaway rjh@purdue.edu
djones@megatest.UUCP (Dave Jones) (02/23/89)
From article <2989@uvacs.cs.Virginia.EDU>, by hsd@uvacs.cs.Virginia.EDU (Harry S. Delugach): [ On how to convince programmers to comment their code... ] > Sometimes it means having a programmer go back to a year-old program and > > try to make efficient changes to it. Sometimes it means getting livid with > ^^^^^^^ ^^^^^ ^^^^ > anger at the long-gone programmer when you have to maintain his/her > ^^^^^ > uncommented code (Do unto others...). I almost never get mad any more. I've decided anger is out of place except, perhaps, when one is fighting other scavengers out on the savanna, something I seldom do, now that the Safeway has opened up down the street. But when I did get angry at programmers, it was never because they did not comment their algorithms. Sometimes I got angry at them for writing convoluted code. But when I was deciphering that stuff, it seemed easier to read the tangled code than to read the tangled comments. ( Somebody who has just written a mess of a program probably will write a real big mess of a comment. ) And I *did* get angry when the comments did not match the code. And I got *livid* when they did not comment the data-structures and variables. Grrrrr, Dave J.
djones@megatest.UUCP (Dave Jones) (02/23/89)
In an article by rjh@cs.purdue.EDU, Bob Hathaway says that he usually uses ADT's to do top-down design and implementation... If it works for him, that's great. I too have been designing all my programs around "abstract data-types" for some time now, although not since my first program, as he has. I started programming for bucks back in '71, when we didn't think of such things. Indeed, I sort of evolved into the practice years later as a result of much head-scratching. Only afterwards did I discover that I was not the only one to have dreamed up the technique. But I don't usually do top-down. I do bottom-up. Design, implementation, test, everything. It actually shocks some people when I say that. In the seventies "bottom-up" became a dirty word. Never mind that top-down methods resulted in some of the most inflexible code every put to disk. Top-down good. Bottom-up bad. Unnngghh. :-) I'll freely admit, there are times when top-down is the way to go. But it's not the way I do most of the programs I write by myself. I start out with a "bottom" that consists of lots of -- okay, I'll go along with the name -- ADT's which are likely to be of use in just about any kind of program: lists, queues, hash-tables, avl-trees, flexible buffers, priority queues and so on. Next I use these to form ADT's which are specific to the low-level objects under consideration, etc. And so it goes from bottom to top. The payoff comes when you want to change something. All you have to do is reshuffle these building blocks, which are still quite useful. But if you go from the top to the bottom, a change at the top is likely to invalidate the whole blasted thing. I sometimes carry it to unlikely extremes. My group is writing a Pascal compiler. If ever there seemed to be a top-down kind of task, that seemed to be it. I mean, Pascal is already done, for Pete's sake. There are standards documents which tell you what a Pascal compiler absolutely *has* to do. But.. I started out with my bag of standard ADT's anyway, and then defined some more: Pascal blocks, types, parms, variable-accesses... just about every kind of Pascal-object you can think of. One by one we implemented them as we worked our way up to type-definitions, expression-trees, statements. The methods for these ADT's went into a library. It was only a matter of a few weeks, long before the compiler's high level was anywhere near finished, that it paid off. Another group was doing a mouse-driven frontend for the interactive embedded compile/load/go feature that we have. They needed to be able to capture all of the type-information, formal parameters and so forth about the program being run, then fish around in it finding all the variables of this type, building all the short expressions that are assignment compatible to the second formal parm of procedure foo, etc.. No problemo. Just link with the new Pascal-compiler-library and do yo thang! I was psyched. Try doing that with a Pascal compiler that was designed top-down to be a Pascal compiler.
ejp@abvax.icd.abnet.com (Ed Prochak) (02/23/89)
After reading several of the comments and replys I just felt some things needed to be said. Since this is long, my main points are: *comments are necessary. *not inserting comments or not updating them is laziness. *not inserting or updating comments costs more money/time later on. *all it takes is a little commitment to do it right the first time. In article <9689@ihlpb.ATT.COM> nevin1@ihlpb.ATT.COM (Liber) writes: >In article <6066@medusa.cs.purdue.edu> rjh@cs.purdue.edu (Bob Hathaway) writes: >|This seems to go backwards. Programmers should first design >|their software then implement it. You seem to be advocating >|implementation then design. The descriptive algorithm should >|come first, then the code. >I have a problem with Top-Down programming (design then >implementation); it happens to be the same problem I have with >Bottom-Up programming (implementation then design). You so eloquently >point it out in your next sentence: >|If the algorithm can be coded in a >|truly self descriptive form no comments will be necessary but in >|instances where the design and implementation are not the same, >|comments help. >But design and implementation should not differ! If this is happening, >one of the two is wrong! In the case of Top-Down, I would guess that >it is probably the design that is wrong; something wasn't taken into >account until someone actually tried to implement the design. The >problem with Top-Down (and Bottom-Up) programming is that there is no >feedback mechanism. What happens when an implementation discovers a >bug in a design? Does it happen that people go back and formally >re-review an already approved design document? Not nearly as often as >it should, I suspect. Or at least go back and change the design to >match the implementation? It gets even worse when there are many >levels to the design. There needs to be a feedback loop. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ GOOD POINT. I know there are companies that do go back to the design document and modify it to match implementation. One is my previous employer, CompuGRAPHIC. What we did was to follow a hardware model. Just as the electrical engineers developed their boards with revisions X1,X2, and so on to initial product shipment, we did design baseline X1, code, test, revise design to X2, and on. It isn't "painless", but it works superbly. Code and design documents did diverge a little, but the differences were usually covered in comments in the code. (The only major module we had trouble with was the one that didn't follow this method.) We had people switching responsibility of modules with good results and a 2year project that was available for initial product shipment in 18months. The point being that even under severe schedule pressure, we did a decent job of maintaining the documentation. >|True, but requiring Joe Programmer to design his software first will help, >|and the design can be included in the comments. EXACTLY. And the design can explain things that would be too verbose to put in the code, such as operating system or performance constraints. Then the comments in the source file can deal with the implementation issues, like segmented memory and compiler limits. >Yes, but until we have good hypertext systems that will allow Joe >Programmer to do this easily and painlessly, he basically has to >maintain TWO design documents, and when a human being has to do it, it >tends to get out of sync, and eventually useless. Knuth has a system that allows this kind of development. I am looking forward to trying it sometime. (when the schedule eases up a bit :^). >|After my experience >|grading and after working with several large programs my conclusion is that >|well commented, self-documenting code is by far the best. Also, forcing >|an a-priori design and including this design in comments will not only >|produce higher quality and better designed programs but programs which are >|more easily understood since the structure of the software is documented. >I agree. And the only way I see this happening is by making this >easier than the other, lazier alternatives. Lazy is the word for it. but the lazyness is not only Joe's, it includes Mike Manager's laziness in not seeing that the documentation and commenting is done. As the sign on the restroom wall says "the job is not finished until the paperwork is complete." >|I agree entirely and advocate languages which allow direct expression of >|algorithms and design. But since current languages are approaching that >|point and are not yet there, commenting is still necessary. >No argument here. I believe as some have stated in other followups that this will not be possible. A programming language describes how to perform some action, but the comments and design should give the why it is being done. >|I think the poorly designed, poorly documented systems have caused most >|of the trouble, not out-of-date commenting. Just follow the convention >|that when code is updated so are the comments. The benefits of a well >|commented design far outweigh the costs. Well documented code is easy >|to understand and modifications to the software can be done in terms of >|the higher-level design. Since the design is directly implemented in the >|code, corresponding changes should be easy. >The real question is: what can we do to make this happen? -- I think it just takes commitment, by programmers and managers. The initial investment in designing and commenting in the beginning produces a large reduction in the cost of maintaining and enhancing a system later. Not documenting is both lazy and inefficient. -- Edward J. Prochak Email: {cvedc,cwjcc,pyramid,decvax,masscomp,uunet}!abvax!ejp Allen-Bradley ICD I think. I think I am. Therefore I AM! 747 Alpha Drive I think? --- The Moody Blues Highland Heights,OH 44143
billwolf@hubcap.clemson.edu (William Thomas Wolfe,2847,) (02/24/89)
From article <2325@goofy.megatest.UUCP>, by djones@megatest.UUCP (Dave Jones): > In an article by rjh@cs.purdue.EDU, Bob Hathaway says that he usually > uses ADT's to do top-down design and implementation. [...] But I don't > usually do top-down. I do bottom-up. Design, implementation, test, > everything. [...] I'll freely admit, there are times when top-down > is the way to go. But it's not the way I do most of the programs I > write by myself. I start out with a "bottom" that consists of lots of > [general-purpose] ADT's [...]. Next I use these to form ADT's which > are specific to the low-level objects under consideration, etc. The relevant literature states, I believe, that most good programmers combine the top-down and bottom-up techniques; the programmer typically starts with two interfaces and a semantic gap, and then builds each interface in the direction of the other in some programmer-dependent ordering, ultimately bridging the gap by joining the two interfaces at some point in the "middle", somewhere between the two. Thus, rather than argue which face of the coin is better than the other one, perhaps the participants in this discussion should recognize that each strategy has its advantages, and that each functions best when applied in conjunction with the other. Bill Wolfe, wtwolfe@hubcap.clemson.edu
gmg@yendor.UUCP (Gary Godfrey) (02/26/89)
From article <EJP.89Feb23100427@abvax.icd.abnet.com>, by ejp@abvax.icd.abnet.com (Ed Prochak): [stuff deleted] > Knuth has a system that allows this kind of development. I am looking > forward to trying it sometime. (when the schedule eases up a bit :^). > I assume you're referring to _Literate_Programming_/Web? I decided at one point to attempt the same thing (in a MUCH more simplistic fashion) under 'C'. All I do is put the "program documentation" in my 'C' comments in the form: /* * miscl stuff... * . * . * %PDOC% * * LATEX * commands + text can go here. * . * . * %ENDPDOC% */ Then all I have is a simple awk script that munges this stuff and converts all the .c files to .tex files. They are chained together by a single file which ties the output files together and provides some cohesion. It seemed to work well as an experiment.... The next thing that I want to do (to take this a step further :-) is to implement what Stallman did in gnu-emacs - put the On-line user documentation as part of the hard documentation. And further still, put the user docuemntation inside the actual code. So we then have something to the effect of: /* * This is a function: * %UDOC% * Press the <enter> key at this point in order to bring up the widget * screen. The F2 and F98 keys will envoke the goggle window and allow * you to spit 37 feet into the air. * %EUDOC% * %PDOC% * This implements the widget screen and goggle functions. It does this * by flamming the dib cretan and tossing the b-span behind it's back. * %EPDOC% */ Not yet..... > Edward J. Prochak Email: {cvedc,cwjcc,pyramid,decvax,masscomp,uunet}!abvax!ejp ----- If ever there was one, then I haven't seen it. In fact, if there wasn't one then I haven't seen it. A->B !A->B. B. Damn. Gary Godfrey - AVA Tech, Reston, VA Phone: (703)264-0074 UUCP: ..uunet!cyclops!media!yendor!gmg