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: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,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: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public From: ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) Subject: Re: Hungarian notation Date: 1996/05/31 Message-ID: <4omejm$j3a@goanna.cs.rmit.EDU.AU>#1/1 X-Deja-AN: 157702684 references: <31999F43.41C67EA6@scn.de> <4o07o9$rfu@seagoon.newcastle.edu.au> <4o1vo3$p2a@news1.ni.net> <4oehnp$onn@goanna.cs.rmit.EDU.AU> organization: Comp Sci, RMIT, Melbourne, Australia newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel nntp-posting-user: ok Date: 1996-05-31T00:00:00+00:00 List-Id: ENGR@GSSI.MV.COM (Michael Furman) writes: >I am afraid it is impossible because your rule is a quite >ambiguous. I generally agree with it, but every time we need to define what >"obvious" mean. For which kind of person? I wouldn't say "ambiguous". I prefer "gnomic", and will accept "vague". The comments I put in code intended to be read by 2nd year students are far more detailed and assume far less than comments I put in code intended to be read by 4th year students. This is actually part of the problem. Students are exposed to a *lot* of "textbook" code, whose authors have put in comments *to explain the LANGUAGE* as well as a the code. Things that a programmer who already knows the language would call "junk comments" are put in to help students who _don't_ know the language well, and students learn to imitate that. I recently bought "The Microsoft(R) Manual of Style for Technical Publications". There is some very good stuff in there. It introduced me to a term I didn't know: "callout" (basically, you have a diagram and a legend and a line that connects the legend to the place in the diagram it comments on). This suggests to me that a better way to annotate code for inclusion in textbooks is - embedded in the code, place the comments you would normally use for a programmer who understands the language but not this particular program - either number the lines, and key language-oriented annotations to the line numbers, perhaps putting code on the left page and annotations on the facing right page - or use callouts for language-oriented annotations. What's a better way? -- Fifty years of programming language research, and we end up with C++ ??? Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci.