Class comments!?
Peter van Rooijen
peter at vanrooijen.com
Tue Oct 26 07:42:10 UTC 2004
Blake wrote:
> On Mon, 18 Oct 2004 16:24:51 -0700, Michael Latta <lattam at mac.com> wrote:
>
>> I favor comments over documentation in some other repository because
>> it increases the chance that the next poor sod to work on my code
>> will be able to find it. The word documents prepared at various
>> points and placed under CM are never as easy to locate as comments in
>> the code.
>
>
> I think what's excited me about this discussion is that I can see a
> comment system that could actually work, if it were externally and
> internally synchronous. Externally, for clients of the system who want
> to use the objects without having to go through the code, and
> internally for those who want or need to get into them. Also, the
> notion of an OO comment system intrigues me, where comments are inherited.
Hi Blake,
You might enjoy studying a documentation feature of Eiffel called 'short
form'. The Eiffel programming language has a form of executable
OO-documentation that is inherited.
This OO-documentation is part of the source code but can easily be
extracted by tools to show only the documentation of each class. A bit
like JavaDoc, but richer. This extracted form is called 'short form'.
But the really cool part is that you can turn on a compiler switch and
have the executable documentation checked, at runtime, against the
actual code and get warned if the code and the executable documentation
disagree in any way.
It's common for Eiffel developers to run their code with the compiler
switches set to run most, or all, of the checks. Thus, when they trust
their 'short form' documentation, they have a good reason to do so.
Cheers,
Peter
More information about the Squeak-dev
mailing list
|