Re: [Avr-libc-corelib] proposed corelib style guide

[Ruddick Lawrence]

We may want to divide the style guide into two sections: code and comments (then we could also do a brief outline of using doxygen).

I think having very detailed guidelines is good, but we have to be careful how we present them. All "stable" code should follow the guidelines to the T, but we don't want to scare off potential developers/contributors by making the learning curve to develop too high. A good module that only follows half of the guidelines is a better start than no module at all.

On Wed, Sep 23, 2009 at 12:31 AM, David Brown <address@hidden> wrote:

Jan Waclawek wrote:

I would add (from the user's viewpoint):

MODULES - Each module will have a usage guideline and a
comprehensible example of use

I would anticipate that users will copy the library files to their
projects, potentially modifying them, rather than use a pre-built
library or such. So the usage guideline should include a method how
to add all that's necessary into a makefile, preferrably "compatible"
with mfile's "standard" output (or shall we attempt to expand mfile's
capabilities accordingly?)

Given that people will copy the files into their projects, it's also important to make it clear how different modules interact, and what files are part of each module.  It might make sense to have modules within their own directory - thus making it as easy as possible to see exactly what is needed.  The directories could also contain test or example code (test code discussions should probably be a new topic).

Sharing between modules should be done when it is beneficial, but only if it really is beneficial.  For example, just because the SPI and Uart modules both use ring buffers, does not mean there should be a separate ringbuffer module that is required for each of them.  On the other hand, if someone writes a great memory pool manager, then a module for implementing web servers should take advantage of it.

Since we expect users to copy files into their projects, it is important to remember that there are no private, internal implementation files. There will always need to be a higher standard of commenting, reader-friendliness and style consistency for "interface" files (i.e., uart.h) than for the implementation files (it is not a big deal if a static variable is named camelCaps rather than camel_caps).  But every file will need a consistent comment block at the start with fields for module summary, copyright and licensing, version and revision information, etc.  There should also be a comment field specifically for "customisation history".  It is very easy for users to forget to add such information at the top of a file they modify, causing confusion later if someone else wants to update the module.  By explicitly adding such a field, we give them an extra reminder.

mvh.,

David