[gambit-list] Truck-Factor by mtov

Hendrik Boom hendrik at topoi.pooq.com
Fri Jul 24 12:46:02 EDT 2015


On Thu, Jul 23, 2015 at 10:58:13PM -0400, William Soukoreff wrote:
> 
> What would have the most impact - commenting inside the source code, or external 
> documentation (perhaps a wiki), or something hybrid, like encoded comments inside 
> the source code that could be "compiled" to viewable comments, similar to, for 
> example, Javadocs)?

I've  found most automatically generated documentation to be nearly worthless.

That said, I think that documentation should be located together with the code it 
documents, and extracted with an automatic documentation engine.

The point is that the documentation still needs to be written.   By people who care 
that the final product is readable, clear, and pricise.  But it needs also to be 
close to the code, so that it can be updated when its code is updated.

There also have to be introductory sections that tie everything together.  These 
sections  often do not belong with any source-code component of the source 
code.  They are essential for someone approaching the system for the first time.

My example of exquisite documentation produced by a documentation generator
is the Trestle Reference Manual:

http://www.std.org/~msm/common/SRC-RR-068.pdf

If you look at the source code for Trestle, you'll find the source code
for the manual there, ofter interspersed in the interface files.
I'm sure that getting it to be coherent when extracted and displayed took significant
effort in the design of the documentation generator and in the source code of the
documented modules.

The immediate practical question in this approach is:

How can we organise a crowd-sourced effort to accomplish this?
A wiki is the usual answer, but it fails in terms of integration with the source 
code, which is essential to keeping it up-to-date with code changes. 

I'd almost want the source-code to be on the wiki, so that people can edit comments 
right into it.  And some mechanism should be available to merge these changes into 
the official source code, with some automatic filter that will ensure that none of 
the chages can affect source code behaviour.  Maybe on that checks that chages are 
only made to comments, or other similar none-active code.

Changes that do not conform to this should be returned to the submitter (in his own 
revision conttrol branch) for reworking, or, after that, for review as a formal patch 
to the active code.

This might be a nontrivial add-on to revision control.

-- hendrik



More information about the Gambit-list mailing list