Re: [Nmh-workers] Questionable code - the bigger picture

[Josh Bressers]

> >  - Better modularity.  All the executable are static, and the current
> >    layout of source lacks clarity.  There are subroutine files in uip, they
> >    belong in sbr (perhaps renaming these directories would be nice too).
> >    We should strive for nmh to really be 2 parts.  mhlib, and the user
> >    interface bits.
> 
> I have no problem with the static executables.  nmh is pretty small as
> programs go these days.  I think than nmh suffers from too-many-small-file
> syndrome.  As I mentioned earlier, I'd like to collect some things into
> larger files, for example context.c, sequences.c, etc.  Although having
> some subroutine files in uip is strange, I really don't mind because it
> works ok; these are subroutines that are used by very few programs.  I
> guess I could go either way on this.  I would go for renaming sbr to lib
> and uip to src.

The executables can still be static, that's just a detail.  By having a
defined line between the user tools, and the backend library, you can help
keep code where it belongs.  Most of the user programs have a mix of
interface code, and what should belong in a library.  It should help cut
down on code duplication.

> > Adding documentation is of course a given.  I've used doxygen in the past,
> > it makes for rather nice API docs.  I think keeping our documentation as
> > close to the code as possible will help keep it accurate and useful.
> 
> I'm not big into automated documentation tools.  The open source world is
> full of very pretty content-free documents produced by automated tools.  I
> think that adding decent comments to the code is the best thing to do.

A tool like doxygen uses the comments in the code to generate the API docs.
It makes you format your comments in a certain manner, but that's not a bad
thing since it keep comments similar (easier to read).  Take a look if you
have time: http://www.doxygen.org.

-- 
    JB