In ideal world, programmers will be editing their programs
with fancy pretty-printing and editing tools. All kinds of
massive annotations would be then possible but they will be
invisible to a programmer's eye and not obscuring
his/her code. Compilers will be clever enough to handle
pretty-printed and annotated source code. But the
programmers will never have to look into those special
files. They will always work with nicely presented views
of the possibly ugly internal representation of the source
code.
But we do not live in such ideal world yet and what we use
daily are ascii editors for developement of our programs.
For a strange reason we are way behind the ordinary
computer users who do not care for ascii editors at all.
Because of our dependence on ascii format I protest those
proposals whose aim is to help some (hypothetical) tools to
generate fancy looking views: interfaces, cross-references,
etc.
No matter what some say, some of us will be still wanting
to work directly with the ascii source code. But if such
code is obscured by all those hints and helpings for
automated tools, such as XML tags and so on, the source code
presentation will be quite ugly and very hard to use
directly.
As someone already said here: programmer's comfort first
of all. Tools suppose to help us, not to impede our
work. If they are not intelligent enough - tough luck,
scrap them and find something better.
How come ISE Eiffel tools can handle all of this so
nicely from a clean ascii, readable source code? As far
as I can remember the only ugly looking comment line sits
somewhere at the top and says something like this:
"Document: $blaha $Date...". But the rest is pretty
-- as it supposed to be.
There are plenty of views that are given to Eiffel
users as his/her choice. And all of them are produced
from the same readable source code on the fly. So-called
short form which ignores inheritance? Here you go!
Flat form, fully blown API with inheritance. Flat-short
form. Extracts of description of classes. Cross references.
Lists of heirs, lists of parents.
The only help a programmer gives to the Eiifel tools
is a bit of self-discipline. Location of comments.
Obligatory class comments. Preconditions and postconditions
that help to clarify the intended usage of the methods.
Licencing garbage at the bottom, not at the front of
the file. Well thought of comments: concise and clear.
I am just looking at one such extract, and -- beside
different representation of signatures -- all of
this look very Haskell! Even comments start with dash-dash. :-)
And it looks really good.
Jan