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: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: fac41,af40e09e753872c X-Google-Attributes: gidfac41,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public From: dewar@cs.nyu.edu (Robert Dewar) Subject: Re: The Last Word on Comments (was Re: Hungarian notation) Date: 1996/07/12 Message-ID: #1/1 X-Deja-AN: 168757051 references: <31bf6e29.185297643@netline-fddi.jpl.nasa.gov> <31C685A1.F1@wgs.estec.esa.nl> <4q79lr$ju5@panix3.panix.com> <4r1bdp$3ib@nntp.seflin.lib.fl.us> <4s3397$9ih@nntp.seflin.lib.fl.us> <4s4gbf$5fm@news.ld.centuryinter.net> organization: Courant Institute of Mathematical Sciences newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-07-12T00:00:00+00:00 List-Id: Jeff said "And I am not at all convinced that "comments are ... at greater liability in this". When the program's behavior seems to disagree with a comment, the comment is easily written-off as probably incorrect." Generally I agree with Jeff, but I do not quite agree with the above. If the comments and a programs behavior in respect to these comments do not agree, then the program has a bug. The bug may be bad comments or it may be bad code, you can't tell a priori, and it is a mistake to assume the code is right *even if the program is 100% reliable and correct in terms of its execution behavior*. We have all seen cases of cancelling bugs in programs, where two pieces of code violate their specs (and hence commens), but the bugs cancel out. I would say that although such a program is correct in a formal sense, it has two bugs in it, and they need correcting, and in this case the commens are right and the code is wrong. The problem comes during maintenance when some bright programmer fixes one of the two bugs, or uses one of the two pieces of code without the other. This kind of emergence of latent bugs is one of the most worrisome aspects of maintenance programming, and is a good reminder that the intended behavior of a program internally is not neccessarily modeled by its actual behavior *even if the program is completely correctly operating*. So you cannot tell the intent of a piece of code just by looking at the code even if you know the program is correct (in the formal sense of the term, i.e. the entire program meets its spec). In such cases, comments can be invaluable in figuring out the intent. Now of course all programs are extensively commented in practice (well nearly all :-) since they use meaningful variable names. If you see a procedure called launch_rocket you assume that it has something to do with launching a rocket. Indeed: procedure action_1096; -- procedure to launch_rocket and procedure launch_rocket; are pretty similar in terms of ones informal understanding of the program. If in eiher case the routine actually causes (and is intended to cause) the rocket to self-destruct, then you have an incorrect and misleading comment in either case (and I would say a bug in either case). P.S. Choosing effective names is an important tool for making programs informally more readable, but I find it dangerous to rely on names alone, they can often mislead at the detail level.