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, MSGID_RANDY autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,e94a7e4f6f888766 X-Google-Attributes: gid103376,public From: Ehud Lamm Subject: Re: Comments (was: Self-referential types) Date: 1999/10/23 Message-ID: <7urumg$cqj$1@nnrp1.deja.com>#1/1 X-Deja-AN: 539506256 References: <7ttb4a$8mq$1@nnrp1.deja.com> <3802f2db_2@news1.prserv.net> <3803B5E3.F96A6DD4@mitre.org> <3803c8bc_2@news1.prserv.net> <3804E7E0.6A0265FB@mitre.org> <38077EB3.E6911567@mitre.org> <380CA5AC.82499FE2@ftw.rsc.raytheon.com> <7um9ji$dor$1@nnrp1.deja.com> <380F2BA5.1EEE15F1@ftw.rsc.raytheon.com> <7ur1gn$q5h$1@nnrp1.deja.com> X-Http-Proxy: 1.0 o-proxy.cc.huji.ac.il:8080 (Squid/2.2.STABLE4), 1.0 x35.deja.com:80 (Squid/1.1.22) for client 132.64.13.108, 132.64.1.34 Organization: Deja.com - Before you buy. X-Article-Creation-Date: Sat Oct 23 09:21:20 1999 GMT X-MyDeja-Info: XMYDJUIDehudlamm Newsgroups: comp.lang.ada X-Http-User-Agent: Mozilla/2.0 (compatible; BiDi MSIE 3.02; Windows 95) Date: 1999-10-23T00:00:00+00:00 List-Id: In article <7ur1gn$q5h$1@nnrp1.deja.com>, Robert Dewar wrote: > In article > ji.ac.il>, > Ehud Lamm wrote: > >4. Don't put in too many comments in the code. I want tov be > able to see > >the code itself. > > I think this is dangerous advice to students, since they hate > commenting, > and a suggestion that puts the don't in front of the "do" here > is upside > down. Over-commenting is easily correctable, a life long > aversion to > writing any comments, which seems to aflict many programmers, is > hard > or impossible to cure. At first students will tend to over > comment a bit, > because they don't understand the code as well as you do, but I > think it is > a tactical mistake to step on that tendency to early on. > I make my student comment like crazy. This just points out that really useless comments are not what I am looking for. I, like you, am very much in favour of thourgh commenting - and no studunet of mine can fail to notice that after seeing the remarks on his first exercise... > But you may choose you own. > After you > >choose, stick to one standard. This is the major part of the guideline, which both you and Ted didn't appreciate. >I particularly dislike the > C-style all caps for constants. So I agree with Ted here. I > don't > think that arbitrary rules like this are the least bit helpful > > X : Universal_Integer_Type; > > is ugly, when obviously the name Universal_Integer is a noun > that is just > right for use as a type name. > Most of the time, esp. in Ada I agree that name like Index_Type and Number_type are not verey elegant. I prefer giving good names (for example following the noun/adjective distinction etc.) - and this is why (among other reasons) I am willing to accept almost any half decent standard -as long as the programmer is consistent. don't call one variable AVARIABLE and the next on iVAR (following Hungarian). Decide what you prefer. We can argue about your choice, but at this is a legitimate argument - in most cases. So why did I give the advice I gave, which both you and Ted don't li,e, and which I myself am not willing to defend "to the death?" Well, you have to remember that for most of my students English is a foreign language. So they tend to use bad names - for lack of vocab or language skills. They tend to miss the noun/verb distinction when naming functions and procedures etc. So instead of saying "choose good names," which may leave them in the dark I give one solution - even if it is not great. They are free to choose their own naming scheme. Usually I don't really mind - so long as the code is readable. One more reason for the guideline is that I want the guidlines to provide information, that may otherwise be lacking. So I prefer giving an exmaple of a standard - even if it is not desribed completly, just so that the students will have a better grasp of what I am talking about. Consider waht I require from comments. I say 'name, student number, question number, and general description of routine." Of course for a hefty package this is barely enough. I know that, and so do they. This is just a beginning. When I teach about packages, ADTs, ADOs - I take time to discuss what seems reasonable to include in the comments accompanying such modules. Thanks for your comments. Maybe some student will see them, and we will have a discussion about it.... -- Ehud Lamm mslamm@mscc.huji.ac.il http://purl.oclc.org/NET/ehudlamm Check it out and subscribe to the E-List Sent via Deja.com http://www.deja.com/ Before you buy.