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=-0.3 required=5.0 tests=BAYES_00, REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 11390f,4c42ac518eba0bbe X-Google-Attributes: gid11390f,public X-Google-Thread: 109fba,4c42ac518eba0bbe X-Google-Attributes: gid109fba,public X-Google-Thread: 1014db,4c42ac518eba0bbe X-Google-Attributes: gid1014db,public X-Google-Thread: 103376,4c42ac518eba0bbe X-Google-Attributes: gid103376,public From: Alan E & Carmel J Brain Subject: Re: Documenting Code (was:Programming language vote - results) Date: 1997/10/31 Message-ID: <3459A84A.246@dynamite.com.au> X-Deja-AN: 285976832 References: <343fbb5a.0@news.iprolink.ch> <343FD05C.8986A557@flash.net> <34428914.2D71D0F@ibm.net> <01bcd87f$7fefcf00$25a43a91@basil.omroep.nl> <34458CE3.507C@dynamite.com.au> <3444BFC6.794BDF32@druid.net> <34466EB4.3381@dynamite.com.au> <6275dt$agm$3@news.on> <344BCED0.2D51@dynamite.com.au> <62idmb$htg$1@news.on> <344DEAA9.5115@hal-pc.org> <01bce1bf$5c2baaa0$95b66bcf@dkelly.ark.com> <345776DD.424B@hal-pc.org> Organization: @home Reply-To: aebrain@dynamite.com.au Newsgroups: comp.lang.ada,comp.lang.apl,comp.lang.c,comp.lang.c++ Date: 1997-10-31T00:00:00+00:00 List-Id: Don Guinn wrote: > > Don Guinn wrote: > > Why is it OK to spend a whole morning understanding a couple pages of > > FORTRAN code, yet it is unreasonable to spend the same amount of time > > with a 2-liner in APL or J which does the same thing? > > I prefer to use APL but I have long ago realized that it is beneficial to > > spread it out a bit rather than use very complex 1 or 2 liners. > You are right. It does make it easier to read if things are spread out. > As far as documenting code. Documentation is wonderful when it adds > information and insight on what the program does. I have seen too many > programs full of documentation which does nothing but repeat what is > already stated in the code itself. It's as if the person who wrote it > can't read his own code. > Documentation needs to explain the concepts used in an application. It > should provide definitions of terms (variables) and possible things to > watch out for. But it should not have to translate the source code into > English. It should not be measured by the pound. My viewpoint: If one is using a language that is "terse", such as APL, where WHAT the thing does is not immediately obvious, then a quickly-read line which explains what the code is _supposed_ to be doing is very helpful. At first glance, it can tell a reader what the code does, more quickly than ploughing through cryptic things like GHTransmit(const char* const X); which is basically a read-only string input to a function. Secondly, comments often tell what the program is _supposed_ to do, not always what it does. This means that a quick-scan of the comments only will not reveal a bug. OTOH a more careful reading, which would reveal the difference between actual and intended, automatically finds the bug and suggests a solution. OK, that's it for documenting WHAT the code does. In many, less terse languages, comments are more useful for describing _why_ something is done. For example (in Ada-83); with Tracker; -- package for Radar Trackers only! with TacticalPicture; -- what's the environment we're in procedure AllocateRadarTrackers (TheTrackerStates in Tracker.StateTableType, TheTacticalPicture in TacticalPicture.BasicRecordType, ResultantTrackerCommands out Tracker.CommandListType) is -- Procedure that, given a table of the current radar tracker -- states, and the tactical picture, decides on what commands -- to give to the radar trackers. -- These commands are then expected to be transmitted to the -- trackers by another procedure. -- Exceptions that can be raised here are: -- AllTrackersKaputException ( The Trackers are all KO ) -- UnexpectedErrorException ( Bug or hardware fault) begin -- and so on and so on end; Note that in this (deliberately) verbose and non-terse example, the variables, procedure, exception and type names are self-explanatory. To some degree, the code _is_ the comment, at least on "what it does". Most of the comments "as such" are either explanations of the intention, or give implications of events. A terser piece of code that is exactly hemeomorphic is: with Trk; with TacPic; procedure TCmds ( T in Trk.Lst, TP in TacPic.TP, Cmds out Trk.Cmds ) is -- Procedure that, given a table of the current radar tracker -- states (Trk.Lst), and the tactical picture (TacPic.TP), decides on -- what commands to give to the radar trackers (Trk.Cmds). -- These commands are then expected to be transmitted to the -- trackers by another procedure. -- Exceptions that can be raised here are: -- ATK ( _A_ll _T_rackers _K_O ) -- FUBAR ( Bug or hardware fault) begin -- etc etc end; Note that despite some bad names, the comments explain what's happening. Without the comments, this would be so cryptic as to be baroque. A translation into C++ would be something like #include TP.h; // Tactical Picture Class #include Trk.h; // Tracker Class Trk::CmdList* TCmds( const Trk::Lst* const TL, const TP::Data* const TP) // Procedure that, given a table of the current radar tracker // states (Trk::Lst), and the tactical picture (TP::TP), decides on // what commands to give to the radar trackers (Trk::Cmds). // These commands are then expected to be transmitted to the // trackers by another procedure. // It's assumed that TL and TP are both going to be used later, so // the pointers have been made const, as well as the data pointed to. // Exceptions that can be thrown here are: // ATK ( _A_ll _T_rackers _K_O ) // FUBAR ( Bug or hardware fault) { // etc etc } When using Hungarian Notation, a lot more verbosity sneaks in, as in the first Ada example, which has an equivalent of Hungarian Notation in it ( Tracker.StateTableType rather than Tracker.State for example) How NOT to do it (in any language): procedure P_12_356( X99 in integer ) is NumberOfBananas : integer; -- The number of Bananas NumberOfBaskets : integer; -- The number of Baskets F : float; begin -- and so on in this deliberately BAD example -- which shows that it's possible to write really bad Ada, -- and make comments that are both verbose and useless, -- but you have to really, really work at it! end; I still for the life of me can't understand why C++ is so popular, yet Ada is described as obsolete, etc etc when for a lot of purposes, Ada is C++ with (usually more) clarity, power and safety belts. Certainly in my experience C++ programmers who've had some exposure to Ada have an advantage over the rest. But never mind. -- aebrain@dynamite.com.au <> <> How doth the little Crocodile | Alan & Carmel Brain| xxxxx Improve his shining tail? | Canberra Australia | xxxxxHxHxxxxxx _MMMMMMMMM_MMMMMMMMM abrain@cs.adfa.oz.au o OO*O^^^^O*OO o oo oo oo oo By pulling MAERKLIN Wagons, in 1/220 Scale