[erlang-questions] Erlang 3000?
Wed Nov 19 22:35:58 CET 2008
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:
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
that can track all derivatives of a module.
We can start with edoc and docbuilder and ... and see how things go ...
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
>> 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.
> Switching to an e-mail client, or some code review application is too
> much work, particularly for smaller contributions.
> erlang-questions mailing list
More information about the erlang-questions