From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.3 required=5.0 tests=BAYES_00,INVALID_MSGID autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: fac41,af40e09e753872c X-Google-Attributes: gidfac41,public X-Google-Thread: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public From: Richard Riehle Subject: Re: The Last Word on Comments (was Re: Hungarian notation) Date: 1996/06/13 Message-ID: #1/1 X-Deja-AN: 160087770 references: <4o07o9$rfu@seagoon.newcastle.edu.au> <4o1vo3$p2a@news1.ni.net> <4oegks$ntn@goanna.cs.rmit.EDU.AU> <31bf6e29.185297643@netline-fddi.jpl.nasa.gov> to: "Kevin D. Quitt" content-type: TEXT/PLAIN; charset=US-ASCII organization: National University, San Diego mime-version: 1.0 newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-06-13T00:00:00+00:00 List-Id: On Thu, 13 Jun 1996, Kevin D. Quitt wrote: > On Mon, 3 Jun 1996 16:24:18 GMT, bobduff@world.std.com (Robert A Duff) wrote: > >Clearly, an Ada program needs fewer comments than an > >assembly language program, and that's a benefit. > > If you have this attitude, you'll never work for me. Comments tell me what > the program is doing and why; the comments are high-level. The code shows > how, with comments to explain unusual techniques. Your assessment of Dr. Duff's value to a project may be a little hasty. Though he is quite capable of defending himself, my guess is that he did not mean to imply that comments were always superfluous, rather that one needs few comments in a high-level language than in a low-level language such as C or Assembler. I recall, from my Assembler days, that nearly every line needed some comment if we intended it to be maintainable. OTOH, on an Ada project, the convention was to comment every exported service in a package specification with a direct or indirect reference to the corresponding paragraph in the original requirements specification document. Comments, in Software Engineering, are as important for traceability as for "what is really going on here?" For projects where the deployed software will involve a human user, we sopmetimes recommend to our clients that they first write the user manual. Then build the software with comments traceable back to chapter and verse of that manual. > When I've led teams with junior people, I've told them that their comments are > much more valuable than their code. If their comments are legit, I can > immediately tell if there's a design problem. And if there isn't a design > problem, I can code from their comments and make it work a whole lot faster > than they can debug. This is undoubtedly true for languages which discourage the programmer form writing code with meaningful data names. In fact, this is precisely the problem with "write only" languages such as C or APL. It is unfortunate that this carries over to much of the C++ code I encounter. C++ does have the potential for supporting self-documenting code even though that potential is seldom realized in practice. In such situations, one is truly dependent on the quality of the line-by-line comments. In languages that stress readability of the final code such as Ada Eiffel, or Modula-x, embedded comments are somewhat less critical. For these kinds of languages, the programmer finds the code itself to be a bit more friendly. In such situations, comments may be helpful. Other times, when the comments are overly verbose or extraneous, their very extraneousness can actually hamper rather than enhance understanding. Richard Riehle