Re: [dpdk-dev] tools brainstorming

[Neil Horman <nhorman@tuxdriver.com>]

On Wed, Apr 08, 2015 at 02:40:59PM +0000, Butler, Siobhan A wrote:
> 
> 
> > -----Original Message-----
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Wednesday, April 8, 2015 2:11 PM
> > To: Butler, Siobhan A
> > Cc: Thomas Monjalon; dev@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@tuxdriver.com]
> > > > Sent: Wednesday, April 8, 2015 12:44 PM
> > > > To: Butler, Siobhan A
> > > > Cc: Thomas Monjalon; dev@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@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?
I've not looked at it yet, this just jumped out at me.  i'll try get to it this
afternoon.

Neil

> S
> > 
> > >
> > >
>