[erlang-questions] Erlang 3000?

[Joe Armstrong]

If we are going to write loads of code we need to answer a number of
questions  and try to define some kind of "best practice"?

What is best practice for testing and and documenting code? Should modules
contain test cases - or should these be in separate files?

Should modules contain APIs or should these be in separate interface documents?

What meta data should a module have?

What is the best way to use:

1) edoc
2) type signatures
3) meta data
4) unit testing
5) cross ref
6) type analysis

Note I say "best way" - not how to use these things ...

and so on ...

I have a feeling that the toolset is important here. There is no
incentive to write
inline tests in the code if this is not backed up with a good
production system. There is
no incentive to write in-line documentation if I can get better
results with off-line LaTeX.

I think we should try to define a minimal set of standards that define
best practice - then make the tools to support the codeing style we adopt.

Personally I don't like stuffing everything into one file - I'd like to see

    X.erl   (the code)
    X.sig   (the interface type signature and terse documentation)
    X.doc  (verbose - high quality documentation)
    X.test  (test cases)

With tools to produce html, pdf, cross listings, indices, reports, ... etc.

Also organisation of code is interesting - when projects are small I
put all code
in the same directory - as they grow the code gets split into
directories - as they get
huge no amount of directory organisation helps - well index'ed meta
data is the only thing
that helps. All modules should probably have a GUID with some kind of
tracking software
that can track all derivatives of a module.

We can start with edoc and docbuilder and ... and see how things go ...

/Joe


On Wed, Nov 19, 2008 at 9:12 PM, Tim Fletcher <twoggle@REDACTED> wrote:
>> We need methods for producing drop-dead-beautiful documentation
>> (in PDF, HTML, ...) - think "book quality"
>
> What tools are used to generate the Erlang PDF manuals? Would they be
> suitable?
>
>
>> We need an infrastructure. The genius of the Wikipedia is that it is
>> an organisational form that allows a lot of people to contribute by
>> doing a little. Correcting a spelling mistake, asking a question,
>> replying to a question has enormous power when done by hundreds or
>> thousands of people.
>
> Agreed. I think using a distributed SCM such as git would be a good
> alternative to a web-based code review tool. The forking and pulling
> workflow supports code review as-is, albeit not explicitly (cf.
> http://shifteleven.com/articles/2008/05/17/code-reviews-inherit-in-git).
> Switching to an e-mail client, or some code review application is too
> much work, particularly for smaller contributions.
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://www.erlang.org/mailman/listinfo/erlang-questions
>