* Comments
@ 1996-11-07 0:00 N.A.Smith
1996-11-11 0:00 ` Comments Hercules Gunter
0 siblings, 1 reply; 13+ messages in thread
From: N.A.Smith @ 1996-11-07 0:00 UTC (permalink / raw)
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
--
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Comments
1996-11-07 0:00 Comments N.A.Smith
@ 1996-11-11 0:00 ` Hercules Gunter
1996-11-13 0:00 ` Comments ennals
0 siblings, 1 reply; 13+ messages in thread
From: Hercules Gunter @ 1996-11-11 0:00 UTC (permalink / raw)
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.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Comments
1996-11-11 0:00 ` Comments Hercules Gunter
@ 1996-11-13 0:00 ` ennals
1996-11-14 0:00 ` Comments Dirk Dickmanns
` (2 more replies)
0 siblings, 3 replies; 13+ messages in thread
From: ennals @ 1996-11-13 0:00 UTC (permalink / raw)
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' "
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Comments
1996-11-13 0:00 ` Comments ennals
@ 1996-11-14 0:00 ` Dirk Dickmanns
1996-11-14 0:00 ` Comments johnherro
1996-11-18 0:00 ` Comments Richard A. O'Keefe
2 siblings, 0 replies; 13+ messages in thread
From: Dirk Dickmanns @ 1996-11-14 0:00 UTC (permalink / raw)
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++
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Comments
1996-11-13 0:00 ` Comments ennals
1996-11-14 0:00 ` Comments Dirk Dickmanns
@ 1996-11-14 0:00 ` johnherro
1996-11-18 0:00 ` Comments Richard A. O'Keefe
2 siblings, 0 replies; 13+ messages in thread
From: johnherro @ 1996-11-14 0:00 UTC (permalink / raw)
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Comments
1996-11-13 0:00 ` Comments ennals
1996-11-14 0:00 ` Comments Dirk Dickmanns
1996-11-14 0:00 ` Comments johnherro
@ 1996-11-18 0:00 ` Richard A. O'Keefe
2 siblings, 0 replies; 13+ messages in thread
From: Richard A. O'Keefe @ 1996-11-18 0:00 UTC (permalink / raw)
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.
^ permalink raw reply [flat|nested] 13+ messages in thread
* Comments
@ 1997-03-12 0:00 Beamish
0 siblings, 0 replies; 13+ messages in thread
From: Beamish @ 1997-03-12 0:00 UTC (permalink / raw)
What is the format for comments in Ada?
Please e-mail me back.
Thanks in Advance.
Beamish
^ permalink raw reply [flat|nested] 13+ messages in thread
[parent not found: <7ttb4a$8mq$1@nnrp1.deja.com>]
* Re: Self-referential types
@ 1999-10-12 0:00 ` Matthew Heaney
1999-10-13 0:00 ` Robert I. Eachus
0 siblings, 1 reply; 13+ messages in thread
From: Matthew Heaney @ 1999-10-12 0:00 UTC (permalink / raw)
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>
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Self-referential types
1999-10-12 0:00 ` Self-referential types Matthew Heaney
@ 1999-10-13 0:00 ` Robert I. Eachus
1999-10-13 0:00 ` Brian Rogoff
0 siblings, 1 reply; 13+ messages in thread
From: Robert I. Eachus @ 1999-10-13 0:00 UTC (permalink / raw)
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...
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Self-referential types
1999-10-13 0:00 ` Robert I. Eachus
@ 1999-10-13 0:00 ` Brian Rogoff
1999-10-15 0:00 ` Robert I. Eachus
0 siblings, 1 reply; 13+ messages in thread
From: Brian Rogoff @ 1999-10-13 0:00 UTC (permalink / raw)
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
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Self-referential types
1999-10-13 0:00 ` Brian Rogoff
@ 1999-10-15 0:00 ` Robert I. Eachus
[not found] ` <slrn80fl9f.68j.aidan@skinner.demon.co.uk>
0 siblings, 1 reply; 13+ messages in thread
From: Robert I. Eachus @ 1999-10-15 0:00 UTC (permalink / raw)
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...
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: Comments
@ 1999-10-25 0:00 Wilhelm Spickermann
0 siblings, 0 replies; 13+ messages in thread
From: Wilhelm Spickermann @ 1999-10-25 0:00 UTC (permalink / raw)
[-- 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
^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~1999-10-28 0:00 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
1996-11-07 0:00 Comments N.A.Smith
1996-11-11 0:00 ` Comments Hercules Gunter
1996-11-13 0:00 ` Comments ennals
1996-11-14 0:00 ` Comments Dirk Dickmanns
1996-11-14 0:00 ` Comments johnherro
1996-11-18 0:00 ` Comments Richard A. O'Keefe
-- strict thread matches above, loose matches on Subject: below --
1997-03-12 0:00 Comments Beamish
[not found] <7ttb4a$8mq$1@nnrp1.deja.com>
1999-10-12 0:00 ` Self-referential types Matthew Heaney
1999-10-13 0:00 ` Robert I. Eachus
1999-10-13 0:00 ` Brian Rogoff
1999-10-15 0:00 ` Robert I. Eachus
[not found] ` <slrn80fl9f.68j.aidan@skinner.demon.co.uk>
1999-10-19 0:00 ` Wes Groleau
1999-10-21 0:00 ` Robert Dewar
1999-10-21 0:00 ` Comments (was: Self-referential types) Wes Groleau
1999-10-21 0:00 ` Ehud Lamm
1999-10-23 0:00 ` Robert Dewar
1999-10-23 0:00 ` Ehud Lamm
1999-10-23 0:00 ` Comments Georg Bauhaus
1999-10-24 0:00 ` Comments Ehud Lamm
1999-10-26 0:00 ` Comments Robert I. Eachus
1999-10-28 0:00 ` Comments Jerry van Dijk
1999-10-28 0:00 ` Comments Ted Dennison
1999-10-25 0:00 Comments Wilhelm Spickermann
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox