Request for the establishment of Umon coding convention

[Gedare Bloom]

On Tue, Jun 23, 2015 at 1:59 PM, Ed Sutter <ed.sutter at alcatel-lucent.com> wrote:
> 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.
This would not be consistent with RTEMS, but a few exceptions is fine.
(although I never understood this one)

> - 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.
This is usually what the doxygen should do for a 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.
We put this in the copyright block. (And, authorship is tracked in Git)

>
> 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
But it should use the APL since that is the license of choice for UMon.

> This is your port, so make sure you put your name in there!
>
> If others have suggestions, go for it...
> Ed
>
>
>
> _______________________________________________
> umon-devel mailing list
> umon-devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/umon-devel