Ross Paterson <[EMAIL PROTECTED]> wrote,
> On Wed, Mar 22, 2000 at 12:44:11PM +0000, Keith Wansbrough wrote:
> > There seems to be some agreement at least that a clean and unintrusive
> > syntax like POD or the ISE Eiffel stuff is preferable to something as
> > noisy as XML; it certainly seems to me that it would be much more
> > rapidly adopted.
>
> A simple approach might ask authors to do the following:
>
> 1. Use Haskell's literate comment convention (either one).
>
> 2. Give explicit type signatures for all exported functions.
>
> 3. Place comments before the things they describe. In particular, module
> overview at the start of the file, interface comments before type
> signatures.
>
> That's not much, but a program could then extract the interface without
> knowing a lot of Haskell.
>
> Extra structure for these comments could be worked out later.
I completely agree with 2 and 3, but why require 1?
Although I like the idea of literate programming, it doesn't
seem to encourage programmers to add comments to "real"
programs (ie, sizeable software). The result are "literate"
programs with 95% code and 5% comments, which are just more
noisy due to the literate comment conventions - look at
ghc's source for what I mean.
Points 2 and 3 work fine with normal comments. I am usually
using the following layout for my Haskell programs:
-- compute the product of two matrices
--
-- * all sublists must be of equal length
--
matMul :: [[a]] -> [[a]] -> [[a]]
--
-- using Strassen's divide&conquer algorithm
--
matMul xss yss = ...
As you propose, the interface comment precedes the type
signature. Everything after it (comments and code) belongs
to the implementation and should not be copied into a pure
interface specification.[1]
IMHO, the biggest obstacle to the proposed scheme are
module-global comments on implementation aspects, ie,
comments that do not belong into the interface and are not
attached to a single function, because they influence the
design of the implementation of the whole module. How can a
tool distinguish these from module-global comments that are
part of the interface description?
One approach to this problem would be to adapt a style
similar to that of the Lisp people, where `;', `;;', `;;;',
and `;;;;' are used for different kinds of comments. We
could use `---' for global comments that are to be copied to
the interface and `--' for comments that shouldn't. This
makes it not only easy for a tool to distinguish the two,
but also gives a human reader a clear understanding of what
the author felt is an assertion about the interface of a
module and what is a comment describing the current state of
the affairs, but which may change in following version of
teh code.
Cheers,
Manuel
[1] Some people might be worried that the type signature is
drowned among the comments. This is not a problem in an
editor using colour-based highlighting of syntactic
forms (a feature that any decent program editor these
days has).
