Comments

Comments

[N.A.Smith]

I am writing a project to automatically insert comments into ADA
programs and I need to obtain information about the industry
standards concerning them. I also need to find out what things
programmers consider important enough to put in the various type
of comments (e.g. procedure heading, package heading etc. etc). If
you think you might be able to help, say by providing me with your
examples or you company's standards (not all of them mind!) then
please visit my web page to find out more.

http://www.brad.ac.uk/~nasmith/comments.html

Thanks

Nick Smith

--

Re: Comments

[Hercules Gunter]

re: automatic commenting of Ada programs

The point of comments is to explain the non-obvious bits of the code. 
It's quality that counts, not quantity.  Anything you can generate
automatically would have to be fairly obvious and of no use to the
person coming later who needs to understand the code.  This is a job for
the human who write the code, or the poor maintenance programmer who had
to figure it out later.

Re: Comments

[ennals]

In article <328828AA.4EF6@wantree.com.au>, Hercules Gunter
<hgunter@wantree.com.au> writes:

>
>re: automatic commenting of Ada programs
>
>The point of comments is to explain the non-obvious bits of the code. 
>It's quality that counts, not quantity.  Anything you can generate
>automatically would have to be fairly obvious and of no use to the
>person coming later who needs to understand the code.  This is a job for
>the human who write the code, or the poor maintenance programmer who had
>to figure it out later.

It can be useful for describing what function calls etc do.
For example I might write a procedure (fake code)

procedure brcp(s : screen ; i : image ; c : colours); 
#desc Build Really Cool Picture on screen %s of image %i with %c colours

Then when I type

brcp(myscreen, megaimage, 256);
the comment would be:

#com Build really coop picture on screen myscreen of image megaimage with
256 colours.

#desc and #com are just example preprocessor tags. You could make them
anything.
When you asked the system to parse some source code it would replace any
#com comments with new ones if there had been changes.

Similar tags can be given for variables and structures.


This system can give surprisingly good results :-))
Often somebody looking at someone elses code won't know what all the
functions and variables are and this kind of system can quickly make code
much more readable.


(excuse the AOL email address)

********************************************************************
Robert Ennals / email: ennals@aol.com
url: http://members.aol.com/ennals/index.html
TaskBar / MemManager / Bubble (visual programming) etc 
"If at first you don't succeed, redefine 'succeed' "

  

Re: Comments

[johnherro]

ennals@aol.com writes:
> (excuse the AOL email address) ...
> Robert Ennals / email: ennals@aol.com
> url: http://members.aol.com/ennals/index.html

I'll excuse you!!!  :-)

- johnherro@aol.com
http://members.aol.com/AdaTutor

Re: Comments

[Dirk Dickmanns]

ennals@aol.com writes:

>procedure brcp(s : screen ; i : image ; c : colours); 
>#desc Build Really Cool Picture on screen %s of image %i with %c colours

>Then when I type

>brcp(myscreen, megaimage, 256);
>the comment would be:

>#com Build really coop picture on screen myscreen of image megaimage with
>256 colours.

>This system can give surprisingly good results :-))

Build_really_cool_picture(
    on_screen => myscreen,
    of_image  => megaimage,
    with_colours => 256);

would be my way to go.  No comment necessary, no further tool to
use, fast to read.

>(excuse the AOL email address)

ok ;-)

Dirk

--
Dirk Dickmanns -- REALIS -- real-time dynamic computer vision
Sun OS 4.1.3; PC Linux; Ada, OCCAM, C, Eiffel, PROLOG, C++

Re: Comments

[Richard A. O'Keefe]

ennals@aol.com writes:

>It can be useful for describing what function calls etc do.
>For example I might write a procedure (fake code)

>procedure brcp(s : screen ; i : image ; c : colours); 
>#desc Build Really Cool Picture on screen %s of image %i with %c colours

But in Ada I can write

	procedure Build_Really_Cool_Picture(
	   Of_Image : in Image;
	   On_Screen: in Screen;
	   Colour_Count: in Positive);

>brcp(myscreen, megaimage, 256);
>the comment would be:

>#com Build really coop picture on screen myscreen of image megaimage with
>256 colours.

and then call it as

	Build_Really_Cool_Picture(Of_Image => Mega_Image,
	   On_Screen => My_Screen, Colour_Count => 256);

If you really want a preprocessor, write one that adds keyword=> to
arguments.
-- 
Mixed Member Proportional---a *great* way to vote!
Richard A. O'Keefe; http://www.cs.rmit.edu.au/%7Eok; RMIT Comp.Sci.

Comments

[Beamish]

What is the format for comments in Ada?
Please e-mail me back.
Thanks in Advance.
    Beamish

Re: Self-referential types

[Matthew Heaney]

In article <3803B5E3.F96A6DD4@mitre.org> , "Robert I. Eachus" 
<eachus@mitre.org> wrote:

>> This is the basis for programming with access discriminants, which is
>> how you do MI in Ada95.
>
>    I have to butt in here.  It may be how you do MI in Ada, and it is
> one way, but I find it ugly.  If you treat a private access type as the
> object, then you have to do a bit more work inside the package, but the
> exterior looks much cleaner, and the users don't have to use 'Access at
> all.  (Often you don't need it inside the package either.)

I think we're in agreement.

I use access discriminants (indeed, taggedness) strictly as an
implementation technique.  As much as possible you want to push the type
composition infrastructure into the private part of the spec.

For example, most of my observer types only privately derive from
Observer_Type; the public part is just "limited private."

with Clock_Timers;
package Digital_Clocks is

  type Digital_Clock (Timer : access Clock_Timer'Class) is
    limited private;

private

  type Control_Type (Clock : access Digital_Clock) is
    new Limited_Controlled with null record;

  type Digital_Clock (Timer : access Clock_Timer'Class) is
    new Observer_Type (Timer) with record
      Control : Control_Type (Digital_Clock'Access);  --!!!
    end record;

end Digital_Clocks;

Here, Digital_Clock "multiply inherits" from two different parent types.
All the machinery is hidden in the private region, exactly where it
belongs.


I do one better when I observe two subjects simultaneously:

with Master_Timers;
with Slave_Timers;
package Digital_Clocks is

  type Digital_Clock
    (Master : access Master_Timer;
     Slave  : access Slave_Timer) is limited private;

private

  type Master_Obs_Type (Clock : access Digital_Clock) is
    new Observer_Type with null record;

  type Slave_Obs_Type (Clock : access Digital_Clock) is
    new Observer_Type with null record;

  type Control_Type (Clock : access Digital_Clock) is
    new Limited_Controlled with null record;

  type Digital_Clock (...) is
    limited record
      Master_Obs : Master_Obs_Type (Digital_Clock'Access);
      Slave_Obs  : Slave_Obs_Type (Digital_Clock'Access);
      Control    : Control_Type (Digital_Clock'Access);
    end record;

end Digital_Clocks;


Here, Digital_Clock "multiply inherits" from three different parent
types.  But all the machinery is hidden in the private region, exactly
where it should be.

In recent article I showed how to observe individual attributes of a
subject, as compared to observing the subject itself.

If you declare the observer types as children of the subject, then you
can even hide the fact that the subject derives from Subject_Type.

Some guys use public taggedness everywhere with gay abandon.  This is
wrong.  Don't use taggedness unless you need to, and if you do, then
hide it in the private region if you can.

Under no circumstances should you have deep inheritance hierarchies.
Make hierarchies broad and shallow; say, an abstract parent type and a
non-abstract sibling derivations.  (This is the approach I use over and
over again in my articles in the Design Patterns archive.)

I realize this is not the OO approach of other languages, but the
benefits are that you have far less coupling.

These examples (and many more) can all be found in the design patterns
archive.

<http://www.acm.org/archives/patterns.html>


I will be discussing this technique this Sunday (17 Oct 99) during my
Design Patterns tutorial, at this year's SIGAda conference.

Matt


--
The political forces that try to eliminate evolution from science
classrooms impose a narrow, sectarian doctrine on our educational
systems. This imposition represents an affront not only to the
constitutional separation of church and state but also to the moral and
intellectual integrity embedded in that constitution.

<http://www.nabt.org/evolutionks.html>

Re: Self-referential types

[Robert I. Eachus]

Matthew Heaney wrote:
> 
> In article <3803B5E3.F96A6DD4@mitre.org> , Iwrote:

> >    I have to butt in here.  It may be how you do MI in Ada, and it is
> > one way, but I find it ugly.  If you treat a private access type as the
> > object, then you have to do a bit more work inside the package, but the
> > exterior looks much cleaner, and the users don't have to use 'Access at
> > all.  (Often you don't need it inside the package either.)
> 
> I think we're in agreement.

   I'm not sure we are, since I was addressing a slightly different
point.
You pass access parameters in cases where I pass a private access type
to
eliminate any visible (to the user of the abstraction) use of 'Access. 
If you need to make subclassing visible, you end up making the use of
access parameters necessary, but I believe that public subclassing is a
bad thing, and that most visible subclassing should be done using
generic packages to do mix-ins.  I wasn't really criticizing your
approach, just pointing out that
Ada supports two different idioms in this area.

> Under no circumstances should you have deep inheritance hierarchies.
> Make hierarchies broad and shallow; say, an abstract parent type and a
> non-abstract sibling derivations.  (This is the approach I use over and
> over again in my articles in the Design Patterns archive.)

  Amen!  Even when I have lots of generic mixins in the private part,
the Ada idiom seems to be that there are three types of classes:
abstract root classes,
intermediate (again abstract) subclasses when doing mixins, and the
(non-abstract) visible classes that actually have objects associated
with them.  In Ada is is almost always a bug to have a non-abstract
parent of a class.
 
> I realize this is not the OO approach of other languages, but the
> benefits are that you have far less coupling.
 
  Amen again.  Have you ever read "Nesting in Ada is for the Birds" by
Lori Clarke, and others?  It was written before Ada 83 was finalized,
and discussed the same beneficial effect on coupling when you removed
nesting of procedures.

-- 

                                        Robert I. Eachus

with Standard_Disclaimer;
use  Standard_Disclaimer;
function Message (Text: in Clever_Ideas) return Better_Ideas is...

Re: Self-referential types

[Brian Rogoff]

On Wed, 13 Oct 1999, Robert I. Eachus wrote:
>   Amen again.  Have you ever read "Nesting in Ada is for the Birds" by
> Lori Clarke, and others?  It was written before Ada 83 was finalized,
> and discussed the same beneficial effect on coupling when you removed
> nesting of procedures.

Does it discuss the detrimental effect on lots of other aspects of Ada
when you remove nesting of procedures?

-- Brian

Re: Self-referential types

[Robert I. Eachus]

Brian Rogoff wrote:
 
> Does it discuss the detrimental effect on lots of other aspects of Ada
> when you remove nesting of procedures?

   Okay, I'll bite what are they?  Note that nesting of procedures
refers to
procedures declared inside other procedures, not procedures called
inside other procedures, or within packages.

   AFIAK, it is almost always poor engineering to declare procedures
within other procedures in Ada. The chief exception is recursive descent
parsers, and even in that case there are good arguments for using
unnested procedures.  Also there are cases where you want to break a
procedure into subunits for implementation reasons:

   procedure A (Some: Parameters) is
     Some_Local: Variables;
     procedure Start is separate;   -- Ed will write
     procedure Do_It is separate;   -- Joe is doing this
     procedure Cleanup is separate; -- Ed again
   begin Start; Do_It; Cleanup; end A;

   Often though, those separates disappear before the code is entered
into the CM system.  Ada lets fold called once procedures back in as
declare blocks with no change in semantic interpretation.

   Note also that I am talking about procedures.  Many (nested)functions
in Ada would be implemented in other languages as macros.  Using such
inlined functions is good programming practice in Ada.  

-- 

                                        Robert I. Eachus

with Standard_Disclaimer;
use  Standard_Disclaimer;
function Message (Text: in Clever_Ideas) return Better_Ideas is...

Re: Self-referential types

[Wes Groleau]

> Personally I use (at least I try too, I don't always succeed) nested
> procedures to increase code clarity.

It generally has that effect for me.

> This reduces the overall clutter in a unit, and I find it a lot easier
> to check my overall logic if I do this, it doesn't eliminate the need
> for comments (or indeed, proper written documentation), but it does
> make the program easier to understand. YMMV.

If good naming conventions are used, it can _greatly_ reduce the need
for comments.

Re: Self-referential types

[Robert Dewar]

In article <380CA5AC.82499FE2@ftw.rsc.raytheon.com>,
  Wes Groleau <wwgrol@ftw.rsc.raytheon.com> wrote:
> If good naming conventions are used, it can _greatly_ reduce
> the need for comments.

My own view is that good names are an *adjunct* to good
comments, not a substitute for them.


Sent via Deja.com http://www.deja.com/
Before you buy.

Comments (was: Self-referential types)

[Wes Groleau]

> > If good naming conventions are used, [nested procedures] 
> > CAN greatly reduce the need for comments.
> 
> My own view is that good names are an *adjunct* to good
> comments, not a substitute for them.

My own view is comments like the following are worse than 
unnecessary, they are pure clutter:

  -- check whether the current transaction is completed
  if Is_Completed (Current_Transaction) then

     -- if so, close the source and destination DB files
     DB_IO.Close (Source);
     DB_IO.Close (Destination);

I can't count the number of times I have seen code (in many 
languages) with many useless comments like the above, but
with NONE of the comments it really needed.

I suspect "my own view" and "your own view" are the same,
but we're applying them to different things.

Re: Comments (was: Self-referential types)

[Ehud Lamm]

On Thu, 21 Oct 1999, Wes Groleau wrote:

|My own view is comments like the following are worse than 
|unnecessary, they are pure clutter:
|
|-- check whether the current transaction is completed
|if Is_Completed (Current_Transaction) then
|

See my "Guidelines for checking exerices" on my Ada page, section 4.
It is stated rather extermely, so don't jump on me...

Ehud Lamm mslamm@mscc.huji.ac.il
http://purl.oclc.org/NET/ehudlamm <== My home on the web 
Check it out and subscribe to the E-List- for interesting essays and more!

Re: Comments (was: Self-referential types)

[Robert Dewar]

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. Do not have comments like "loop from 1 to 10"
- I can
>read the code. Comments SHOULD appear at the start of logical
sections
>(those that have a specific functionality).

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.

>5. Use a coding convention that distinguishes types/variables
and
>constants. I suggest name like "Student_Record" for variables
(first
>letter capitalized), names like MAXSTUDENT fro constants, and
names like
>student_record_type for types. But you may choose you own.
After you
>choose, stick to one standard.

I do not consider this helpful at all, and 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.


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Comments (was: Self-referential types)

[Ehud Lamm]

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.

Re: Comments

[Georg Bauhaus]

Ehud Lamm <mslamm@mscc.huji.ac.il> wrote:

: 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, wouldn't it seem advisable to have "Natural Language
Skills" in the curriculum? At least for non-english speakers
(like me :-|)?  While there is ongoing talk about The
Globalisation (again), I can see that students are advised
to learn a foreign language, but are otherwise left alone -
the plans for their time at universities do not, in general,
explicitely include slots for other skill that are nevertheless
considered essential.

As an aside, knowing how to use a typewriter seems also to be
helpful, yet this isn't taught, is it? :-)

-# Georg Bauhaus

Re: Comments

[Ehud Lamm]

In article <7usvo6$9kq$1@news-hrz.uni-duisburg.de>,
  Georg Bauhaus <georg@zorro.uni-duisburg.de> wrote:

>
> So, wouldn't it seem advisable to have "Natural Language
> Skills" in the curriculum? At least for non-english speakers
> (like me :-|)?  While there is ongoing talk about The
> Globalisation (again), I can see that students are advised
> to learn a foreign language, but are otherwise left alone -
> the plans for their time at universities do not, in general,
> explicitely include slots for other skill that are nevertheless
> considered essential.
>

The students must pass an exam on English as a second language, or pass an
English course. But this just isn't enough.

I am all for language skills. Alas most people lack them - even in their
native tongues.

Most people fial in phrasing questions, so it is natural that student fail in
phrasing answers - even when they know them!

(By the way: i started a thread on this in several groups, under the title
"formulating good questions").

This is whole subject is off topic here. But as often mentioned in other
groups Dijkstra suposedly said that you can tell if someone is a good
programmer by judging their native language skills.

--
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.

Re: Comments

[Robert I. Eachus]

Ehud Lamm wrote:
 
> This is whole subject is off topic here. But as often mentioned in other
> groups Dijkstra suposedly said that you can tell if someone is a good
> programmer by judging their native language skills.

   Let's not try to make this an urban legend.  He said exactly that.
Well, I think his exact words were: "The best predictor of a student's
success as a software engineer is his skill in using his native native
language."  In any case, he said it at a software engineering conference
in early June 1979--over twenty years ago, ouch!  He also said that if
he was running a school to teach programming, he would tie the student's
hands behind their backs for the first year.

   In the discussion following, Dijkstra pointed out that to be a
compiler developer, you had to speak English, Dutch, German, or Russian
as a young child, even if it was not your "milk tongue."

-- 

                                        Robert I. Eachus

with Standard_Disclaimer;
use  Standard_Disclaimer;
function Message (Text: in Clever_Ideas) return Better_Ideas is...

Re: Comments

[Jerry van Dijk]

In article <38162C84.A762A730@mitre.org> eachus@mitre.org writes:

>   In the discussion following, Dijkstra pointed out that to be a
>compiler developer, you had to speak English, Dutch, German, or Russian
>as a young child, even if it was not your "milk tongue."

Wow, with three out of four I qualify...

:-) :-)

--
--  Jerry van Dijk  | email: jdijk@acm.org
--  Team-Ada        | www:   stad.dsl.nl/~jvandyk
--  Paris, France   | Leiden, Holland

Re: Comments

[Ted Dennison]

In article <941090045.3snx@jvdsys.stuyts.nl>,
  jerry@jvdsys.stuyts.nl wrote:
> In article <38162C84.A762A730@mitre.org> eachus@mitre.org writes:
>
> >   In the discussion following, Dijkstra pointed out that to be a
> >compiler developer, you had to speak English, Dutch, German, or
Russian
> >as a young child, even if it was not your "milk tongue."
>
> Wow, with three out of four I qualify...
>
> :-) :-)
>
> --
> --  Jerry van Dijk  | email: jdijk@acm.org

Well, we shouldn't be horribly shocked that he'd make statements
calculated to raise our estimation of developers whose last names start
with "Dijk". :-)

--
T.E.D.


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Comments

[Wilhelm Spickermann]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=us-ascii, Size: 441 bytes --]


On 24-Oct-99 Ehud Lamm wrote:
..
> groups Dijkstra suposedly said that you can tell if someone is a good
> programmer by judging their native language skills.
..

He wrote in EWD498 (1975):
"Besides a mathematical inclination, an exceptionally good mastery of
one�s native tongue is the most vital asset of a competent programmer."

(Edsger W. Dijkstra: Selected Writings on Computing: A Personal
Perspective, Springer 1982)

Wilhelm