Request for the establishment of Umon coding convention

[Ed Sutter]

On 6/23/2015 1:17 PM, Gedare Bloom wrote:
> On Tue, Jun 23, 2015 at 1:11 PM, Jarielle Catbagan
> <jcatbagan93 at gmail.com> wrote:
>> Hello all:
>>
>> As of right now, there is no firmly established coding convention for
>> Umon.  I would like to start this conversation in working towards
>> establishing Umon's coding convention and then possibly developing a
>> corresponding file or creating a wiki at rtems.org elaborating this
>> coding convention.  This information would include how Umon
>> development should be done as well.  An exception to the approach
>> previously stated is if an existing coding convention is used instead.
>>
>> Please let me know on how we should proceed.
> First identify the prevailing style. Perhaps look at some style tools
> (e.g. uncrustify) to see what kind of style rules are common. Then see
> if the prevailing style is similar enough to any other style that you
> could just adopt it. Otherwise, we have to consider whether to define
> the style rules from the existing code, or to adopt a style guide and
> change the code. Now is the best time to do either, while the code
> base and number of developers is small.
>
I'm not very good at this. I tend to format a file based on my mood, and 
on any
given day that can vary.  But while I'm in that mood, its rock solid 
consistent!
:-)

Seriously, I suggest we attempt to adhere to the same style as is 
outlined in the
RTEMS coding conventions: 
https://devel.rtems.org/wiki/Developer/Coding/Conventions
On the other hand, if that implies that we have to tear up the core 
code, I'd really rather
not do that (but I can be persuaded if really important).   I'll gladly 
go through the core code
and adjust the file headers for doxygen formatting (eventually); but for 
now, lets assume that
this applies to new code (i.e. all the stuff Jarielle is adding). Ok?

A few things I prefer (but I admit not to be 100% consistent with)...
- Start a function name at the beginning of the line, putting its return 
type above it on previous line.
- For text describing a function, whenever possible put that text above 
the function, not embedded
   within the lines of the code (except for simple 1-line comments). IF 
space is needed for explanation
   then use "see noteX above" rather than putting a paragraph within the 
function.
- Most of the code currently assumes vi with ts=4; but I realize that 
spaces do turn out cleaner so
   I'll adapt.
- Typically, the author and contributor's names should be in the file 
header but I suppose that's
    up to the writer.

Not sure how far to go with this, so unless others object, Jarielle, for 
any "headerless files" in the
port directory, why not start with the doxygen header block here:
https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header
This is your port, so make sure you put your name in there!

If others have suggestions, go for it...
Ed