Request for the establishment of Umon coding convention

[Ed Sutter]

On 6/23/2015 2:22 PM, Gedare Bloom wrote:
> 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)
Easier to search for a function:  (in vi: ^funcname)
>
>> - 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.
Still, in the actual code, if I'm writing/modifying a function I'd 
rather have long
comments above, not embedded.
>
>> - 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)
Ok, do that then...
>
>> 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.
Right..
>
>> 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


-- 
Ed Sutter
Alcatel-Lucent Technologies -- Bell Laboratories
Phone: 908-582-2351
Email: ed.sutter at alcatel-lucent.com