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

[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

[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

[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: 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

[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

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.