Path: utzoo!utgpu!utstat!jarvis.csri.toronto.edu!mailrus!csd4.milw.wisc.edu!nic.MR.NET!umn-d-ub!rutgers!att!ihlpb!nevin1 From: nevin1@ihlpb.ATT.COM (Liber) Newsgroups: comp.software-eng Subject: Re: comments on comments Keywords: comments Message-ID: <9689@ihlpb.ATT.COM> Date: 22 Feb 89 02:33:31 GMT References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM> <6066@medusa.cs.purdue.edu> Reply-To: nevin1@ihlpb.UUCP (55528-Liber,N.J.) Organization: AT&T Bell Laboratories - Naperville, Illinois Lines: 67 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!" / (_