Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!cwjcc!abvax!ejp From: ejp@abvax.icd.abnet.com (Ed Prochak) Newsgroups: comp.software-eng Subject: Re: comments on comments Message-ID: Date: 23 Feb 89 15:04:27 GMT References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM> <6066@medusa.cs.purdue.edu> <9689@ihlpb.ATT.COM> Sender: news@abvax.UUCP Distribution: usa Organization: Allen-Bradley Lines: 119 In-reply-to: nevin1@ihlpb.ATT.COM's message of 22 Feb 89 02:33:31 GMT 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