[clean-list] Comments on the module system

[Marco Kesseler]

Hi Maks,

>On Tuesday 23 July 2002 18:12, Brian Rogoff wrote:
>>      In Clean 2, we don't need to repeat macro, type and class definitions
>> from the defition module in the implementation module, which is
>> nice. However, we still need to have an empty .icl if it is needed. It's a
>> petty complaint, but it would be nice if we could omit it.
>
>Personally, I don't think it's all that useful to be able to omit macro, type
>and class definitions, when you still have to type over your (exported)
>function type definitions. Writing definition files usually boils down to
>copy-pasting the implementation code (which can be tested perfectly from
>within a main module) and cutting out the implementation parts, or at least
>that's how it works for me. Also removing macro, type and class definitions
>from the implementation file only makes matters more complicated.

I find the possibilty to omit definitions from the implementation 
module VERY useful. Not so much for new modules, as then things 
mostly proceed as you describe above, but rather for existing ones 
that get modified. I am VERY glad that I don't have to modify things 
twice anymore.

Note that you do not HAVE to do things this way, if you do not like to.

>I don't like doing things that a machine could have done for me just as good
>(or in some cases even better), especially if I have to do them the exact
>same way every singly time I create a module (since you can't create anything
>but a main module without a definition file).  Also, whenever I decide to
>change a function definition, I have to modify both the implementation and
>declaration file.

A machine does not know which definitions you want to make publicly 
known. It also does not know which types need to be abstract.

>Also, I don't like to have two places where I have to comment my code. Since
>the declaration file is where the 'users' (mostly myself, ofcourse) of the
>libraries will be looking for meaningful documentation, some (high-level)
>explanation of the exported functions must go there. If I were to distribute
>a binary version of the module along with only the declaration file, it
>should still be usuable, so there is no way to avoid documenting the
>declaration file.

Having separate dcl and icl files at least makes it possible to 
release a binary version of a module. And what is the problem of 
documenting a declaration file? I would think that a dcl file is 
_the_ place to put comments concerning the exported interface.

>However, for my own convenience, I want to place (more low-level) comments
>near functions that I do not export (directly) as well. Documenting
>implementation code is a necessity when using a programming language like
>Clean, which is hard to read because it is so concise. This means there is
>really no way to avoid documenting my code in two separate files, possibly
>placing double comments with functions that are both exported and
>implemented.

In my opinion, it is a good thing to have low level implementation 
details documented in an icl file, and the exported interface 
documented in the dcl file.

Yes, this sometimes leads to some duplication, but I find this 
problem has become less now we don't have to duplicate much code in 
the icl file anymore.

>Although I acknowledge the advantages of separating the implementation code
>and the definition file, I don't think it is the programmer's job to generate
>the declaration files. Given an implementation file, it's obvious what the
>definition file should look like.

I don't think so.

>Having the compiler generate declaration files would not only allow the
>programmer to focus on more productive (and stimulating) tasks, 

Having to design a proper interface is a productive task I think.

>but would
>also ease code documentation (ie. all documentation could go in the only
>source file)

I think it makes sense to have implementation and interface 
documentation separated. It may not always be easy, but it is important.

>and prevent common errors that result from function definitions
>not matching their implementation.

The compiler will inform you, so what errors do you mean?

>This is now possible, but makes no sense since it could never work.

I do not understand this sentence.

regards,
Marco