OPNFV Coding Guidelines

Note: This document is a work in progress. Fundamentally stolen with pride at this time…

For Git commit messages we recommend following the OpenStack commit message recommendations. See: https://wiki.openstack.org/wiki/GitCommitMessages

• Provide a brief description of the change in the first line.
• Insert a single blank line after the first line.
• Provide a detailed description of the change in the following lines. Use breaking paragraphs where needed.
• The first line should be limited to 50 characters; should be written in present tense; and should not end with a period.
• Subsequent lines should be wrapped at 72 characters.

The commit message must contain all the information required to fully understand & review the patch for correctness. Less is not more. More is more.

Ensure there is only one "logical change" per commit. There are many reasons why this is an important rule:

• The lesat amount of code being changed, the quicker and easier it is to review and identify potential flaws.
• If a change is found to be flawed later, it may be necessary to revert the broken commit. This is much easier to do if there are not other unrelated code changes entangled with the original commit.
• When troubleshooting problems using Git's bisect capability; small well-defined changes will aid in isolating exactly where the code problem was introduced.
• When browsing history using Git's annotate/blame, small well defined changes also aid in isolating exactly where a piece of code came from and why.

Headers must be applied to all contributed code. These should provide a copyright notice identifying the individual, and company where affiliated, of origin for the contribution and the license under which the contribution was made. In OPNFV we use the Apache 2.0 license, some templates for code headers follow.

/*******************************************************************************
* Copyright (c) 2015 <Company or Individual> and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Apache License, Version 2.0
* which accompanies this distribution, and is available at
* http://www.apache.org/licenses/LICENSE-2.0
*******************************************************************************/

##############################################################################
# Copyright (c) 2015 <Company or Individual> and others.
#
# All rights reserved. This program and the accompanying materials
# are made available under the terms of the Apache License, Version 2.0
# which accompanies this distribution, and is available at
# http://www.apache.org/licenses/LICENSE-2.0
##############################################################################

<!--
Copyright (c) 2015 <Company or Individual> and others.

All rights reserved. This program and the accompanying materials
are made available under the terms of the Apache License, Version 2.0
which accompanies this distribution, and is available at
http://www.apache.org/licenses/LICENSE-2.0-->

Per OPNFV IP Policy, all documentation will be received and made available by the OPNFV Project under the Creative Commons Attribution 4.0 International License.

All documentation files need to be licensed using the creative commons licence. The following example may be applied in the first lines of all contributed RST files:

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
.. (c) <optionally add copywriters name>

These lines will not be rendered in the html and pdf files.

Depends on the upstream project to which we intend to contribute to. If it's OPNFV specific 120 character line length would suffice. Yet, for OpenStack, a lot of projects enforce an 80 character length limit.

In General we follow the Google Java Code Style Guide with a few exceptions. See: https://google-styleguide.googlecode.com/svn/trunk/javaguide.html

* 120 character line length * 72 or 80 chars for javadoc

PEP8 is the Python standard that should be followed when coding any Python code with the following exceptions.

* 80 character line length

The usage of tools such as flake8 is encouraged.