Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This is to avoid multiple definitions, and to ensure that the ifndef checks a unique identifier.

File Includes


Code Block
/** @addtogroup XXX_API XXX Public API

...


* Description.

...


* @{

...


*/

...



/*****************************************************************************

...


* STANDARD INCLUDE FILES

...


*****************************************************************************/

...


#include <stdint.h>

...



/*****************************************************************************

...


* PROJECT-SPECIFIC INCLUDE FILES

...


*****************************************************************************/

...


//#include "xxx_misc.h"

...



#ifdef __cplusplus

...


extern "C"

...


{

...


#endif


Functions

Every function should have a function banner as follows :

/* XXX_function name : . */


Code Block
/**

...


* Description.

...

 Briefly describe what the function does

...


*  Parameters :

...

 List all function parameters and provide a description of each parameter along * with the type of the parameter.

...



* (A table with parameter Name, Description, And * Type may be created for *clarity.)

...



* @param[in] arg1 Some argument.

...


...


* @return The status of the operation.

...


* @retval XXX_OK if successful.

...


* @retval XXX_ERR_NOTINIT if the module was not initialised. 

...


* @retval XXX_ERR_BADPARAM if a bad parameter was supplied.

...


...


* @execution Synchronous.

...


* @sideeffect None.

...


*

...


* @note This function must not suspend and must not invoke any blocking system 

...


* calls. It should probably just send a message to a driver event handler task. 

...


*

...


* @see XXX_SomeOtherFunction.

...


*/


Visual Impact

Size

A printed page should be no more than 72 columns.

...

Coding standards for Python

Resources : Documents/Tools

  • PEP8      -  coding conventions  SI team use to write / format SI python scripts.
  • PEP257  -  documentation conventions;
  • Google Python Style Guide -  python practices;
  • Pylint  - default code analysis tool SI team use to verify python code There are 2 more tools that may complement the checking:

                    https://github.com/jcrocholl/pep8  - enforces PEP8 checks;

                    http://pychecker.sourceforge.net/ - Google recommends in its doc;

Rule #0 

The main rule that takes precedence in any language.

Google coding style: BE CONSISTENT.

  • If you're editing code, take a few minutes to look at the code around you and determine its style.
  • If they use spaces around all their arithmetic operators, you should too.
  • If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.
  • The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you're saying rather than on how you're saying it.
  • If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

Naming

Type

Public

Internal

Packageslower_with_under
Moduleslower_with_under_lower_with_under
ClassesCapWords_CapWords
ExceptionsCapWords
Functionslower_with_under()_lower_with_under()
Global/Class ConstantsCAPS_WITH_UNDER_CAPS_WITH_UNDER
Global/Class Variableslower_with_under_lower_with_under
Instance Variableslower_with_under_lower_with_under (protected) or __lower_with_under (private)
Method Nameslower_with_under()_lower_with_under() (protected) or __lower_with_under() (private)
Function/Method Parameterslower_with_under
Local Variableslower_with_under

Names to avoid

  • single character names except for counters or iterators
  • dashes (-) in any package/module name
  • __double_leading_and_trailing_underscore__ names (reserved by Python)

Line Length

  • Maximum line length is 100 characters. 
  • This deviates from PEP8 / Google recommendations. 
  • Rationale: we don't have devices that may need use 80 characters per line. 100 is a reasonable length that fit line on 14-17" monitors.
  • Use wrapping for really long lines as it is described in http://www.python.org/dev/peps/pep-0008/#maximum-line-length
  • Try to not use slash to split the lines.
  • But in contrast to google guide mixing both styles is okay for SI scripts. The main thing is to avoid long lines forcing reader to scroll code back and forth.
  •  

Indentation

  • Indent code blocks with 4 spaces. Never mix spaces and tabs.

PyLint:use code checkers

  • Install and use pylint for the code written as much as possible. Catch problems earlier. Please note that this is just a tool.
  • Always review warnings / errors, and if some of them can be safely ignored or tool just confusing - suppress them.
  • Don't leave warnings in code - suppress. If there are many warnings that may be ignored, important things can be missed due to this noise.

Documentation

  • All public classes, methods, variables should be documented.  Refer to PEP257 for more details.

Code documentation guidelines

General Guidelines

Only one statement per line.

Indentation- K&R style for opening and control statement.
Braces must be always apply to control statements even if the control block only has a single statement.

...

  • Opening statements - brace under function name

...

  •  control statement - brace same line as control statement

...

  • tab = 4 spaces.

Array initialization - array items on separate lines. 

Feature Specific Support

  • Each component must include a configuration file for enabling or disabling a specific RDK feature.
  • Every feature must be capable of enabled or disabled using a configuration.

Naming Conventions

  • Folder names in lower case separated by underscores where appropriate to communicate meaning.
  • Class names in UpperCamelCase.
  • Function, variables and constant names in lowerCamelCase.

Documentation Conventions