Re: Comments (was: Self-referential types)

[Ehud Lamm <mslamm@mscc.huji.ac.il>]

In article <7ur1gn$q5h$1@nnrp1.deja.com>,
  Robert Dewar <robert_dewar@my-deja.com> wrote:
> In article
> <Pine.A41.3.96-heb-2.07.991021191504.30582K-100000@pluto.mscc.hu
> ji.ac.il>,
>   Ehud Lamm <mslamm@mscc.huji.ac.il> 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.