...
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 |
---|
Packages | lower_with_under |
|
Modules | lower_with_under | _lower_with_under |
Classes | CapWords | _CapWords |
Exceptions | CapWords |
|
Functions | lower_with_under() | _lower_with_under() |
Global/Class Constants | CAPS_WITH_UNDER | _CAPS_WITH_UNDER |
Global/Class Variables | lower_with_under | _lower_with_under |
Instance Variables | lower_with_under | _lower_with_under (protected) or __lower_with_under (private) |
Method Names | lower_with_under() | _lower_with_under() (protected) or __lower_with_under() (private) |
Function/Method Parameters | lower_with_under |
|
Local Variables | lower_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
...
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
- Code documentation must comply with Drupal Documentation Standards.which is based on the Doxygen documentation standard.