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

[Jon Steinhart]

> >     1.  Clean up the code.  Make it use more modern (at least Posix)
> >         system features, get rid of code that was there to work with
> >         really broken systems.  Document the code.
> > ...

> I think you've hit the nail on the head with your list.  #1 being the most
> important task.  I've already submitted a few patches to the patch system
> in savannah, with much more work to be done.
> 
> ...

OK, no particular argument here.  But I think that we have slightly different
ideas on how to go about it.  Taking 'em one at a time:

>  - Better error checking/handling (I found a number of unchecked malloc
>    calls for example)

Yup.  I'm fixing all of the ones that I find as I go along.  I'm taking it a
bit farther in some places, like all of the "bug" warnings in the context
stuff.  I'm trying to fix the code.

>  - Less duplication.  There is a ton of code duplication.  There are also a
>    number of functions I've seen that POSIX can handle.

Yes, I'm changing stuff to POSIX functions where reasonable.  There are a few
cases where I'm not, such as getcpy() because it provides extra error checking
that a raw strdup() doesn't and I don't want to duplicate the error checking
code all over the place.

>  - 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.

>  - Naming clarity.  Right now it appears all the functions and variables
>    are named whatever the author wanted to call them.  I think some naming
>    and style guidelines are in order.

I don't see this one as being very worthwhile.  It's in the 
might-be-nice-to-have
category.  Most of the names aren't too bad once you understand the code and 
know
what they mean.  Documentation is needed more than name changes in my opinion.

> 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.

Jon