[dpdk-dev] tools brainstorming

[Neil Horman]

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