[dpdk-dev] tools brainstorming

[Jay Rolette]

"C comments" includes //, right? It's been part of the C standard for a long time now...

Sent from my iPhone

> On Apr 8, 2015, at 8:40 AM, Butler, Siobhan A <siobhan.a.butler at intel.com> wrote:
> 
> 
> 
>> -----Original Message-----
>> From: Neil Horman [mailto:nhorman at tuxdriver.com]
>> Sent: Wednesday, April 8, 2015 2:11 PM
>> To: Butler, Siobhan A
>> Cc: Thomas Monjalon; dev at dpdk.org
>> Subject: Re: [dpdk-dev] tools brainstorming
>> 
>>> On Wed, Apr 08, 2015 at 12:16:10PM +0000, Butler, Siobhan A wrote:
>>> 
>>> 
>>>> -----Original Message-----
>>>> From: Neil Horman [mailto:nhorman at tuxdriver.com]
>>>> Sent: Wednesday, April 8, 2015 12:44 PM
>>>> To: Butler, Siobhan A
>>>> Cc: Thomas Monjalon; dev at dpdk.org
>>>> Subject: Re: [dpdk-dev] tools brainstorming
>>>> 
>>>>> On Wed, Apr 08, 2015 at 10:43:53AM +0000, Butler, Siobhan A wrote:
>>>>> Hi all,
>>>>> To add to the tools brainstorming - I propose we use the following
>>>>> Coding
>>>> Standards as the basis of guidelines on coding style going forward.
>>>>> The style outlined below is in alignment with the current
>>>>> convention used
>>>> for the majority of the project.
>>>>> Any thoughts/suggestions or feedback welcome.
>>>>> Thanks
>>>>> Siobhan :)
>>>>> <siobhan.a.butler at intel.com>
>>>>> 
>>>>> 
>>>>> 
>>>>> Coding Style
>>>>> ~~~~~~~~~~
>>>>> 
>>>>> Description
>>>>> -----------
>>>>> 
>>>>> This document specifies the preferred style for source files in
>>>>> the DPDK
>>>> source tree.
>>>>> It is based on the Linux Kernel coding guidelines and the FreeBSD
>>>>> 7.2 Kernel Developer's Manual (see man style(9)), but was heavily
>>>>> modified for
>>>> the needs of the DPDK. Many of the style rules are implicit in the
>> examples.
>>>>> Be careful to check the examples before assuming that style is
>>>>> silent on an
>>>> issue.
>>>>> 
>>>>> General Guidelines
>>>>> ------------------
>>>>> 
>>>>> The rules and guidelines given in this document cannot cover every
>>>> situation, so the following general guidelines should be used as a fallback:
>>>>> The code style should be consistent within each individual file,
>>>>> and within each file in a given directory or module - in the case
>>>>> of creating new
>>>> files The primary reason for coding standards is to increase code
>>>> readability and comprehensibility, therefore always use whatever
>>>> option will make the code easiest to read.
>>>>> 
>>>>> The following more specific recommendations apply to all sections,
>>>>> both for
>>>> C and assembly code:
>>>>> Line length is recommended to be not more than 80 characters,
>>>>> including comments. [Tab stop size should be assumed to be at
>>>>> least 4-
>>>> characters wide] Indentation should be to no more than 3 levels deep.
>>>>> NOTE The above are recommendations, and not hard limits. However,
>>>>> it is
>>>> expected that the recommendations should be followed in all but the
>>>> rarest situations.
>>>>> C Comment Style
>>>>> 
>>>>> Usual Comments
>>>>> --------------
>>>>> 
>>>>> These comments should be used in normal cases. To document a
>>>>> public
>>>> API, a doxygen-like format must be used: refer to Doxygen
>> Documentation.
>>>>> /*
>>>>>  * VERY important single-line comments look like this.
>>>>>  */
>>>>> 
>>>>> /* Most single-line comments look like this. */
>>>>> 
>>>>> /*
>>>>>  * Multi-line comments look like this.  Make them real sentences. Fill
>>>>>  * them so they look like real paragraphs.
>>>>>  */
>>>>> 
>>>>> License Header
>>>>> --------------
>>>>> 
>>>>> Each file should begin with a special comment tag which will
>>>>> contain the
>>>> appropriate copyright and license for the file (Generally BSD License).
>>>>> After any copyright header, a blank line should be left before any
>>>>> other
>>>> contents, e.g. include statements in a C file.
>>>> 
>>>> This can become very confusing.  There already is a LICENSE.GPL and
>>>> LICENSE.LGPL file at the top of the project, allowing others to
>>>> insert their own licenses within their files can make it difficult
>>>> for end user to determine if it is legally safe to use a given project.
>>>> 
>>>> I'd suggest instead that contributions be disallowed from including
>>>> license files in their code, relying instead on only a single
>>>> license at the top of the project (which should likely be BSD or LGPL, since
>> we're shipping a library).
>>>> 
>>>> IANAL, but it seems to me to be dangerous to do anything else.  For
>>>> example, all the code that is dual licensed in the library (like
>>>> rte_pci_dev_ids.h).  It allows for a BSD or GPL license.  If someone
>>>> builds dpdk as a DSO and distributes it under the former, every
>>>> application that links against that re-distribution may arguably
>>>> itself become GPL licensed.  While I'm personally fine with that, I
>>>> can see it as being a big deal to some end users.  Unifying the
>>>> license makes the re-distribution license issue more clear for everyone.
>>>> 
>>>> Neil
>>> 
>>> 
>>> Input appreciated Neil thank you, would it be best to include this in one of
>> the community conference calls?
>>> IANAL either ( yet at least :) ) - we can certainly consult with someone who
>> has the expertise.
>>> If others are interested in discussing this we can get added to the agenda
>> for an upcoming call.
>>> 
>>> Is more detailed explanation/notice on the licensing structure required?
>>> Thanks,
>>> Siobhan
>> If you want to discuss it on the community call I think that would be fine,
>> certainly, but it seems that on this forum is the real place to encourage
>> conversation.  Its recorded for posterity, and is open to the entire
>> community, all we need are people to speak up.
>> 
>> Neil
> Fair enough - no issue with that either. 
> The license section aside, do you think the coding style is ok?
> S
>> 
>>> 
>>>