diff --git a/doc/Pacemaker_Development/en-US/Ch-Coding.txt b/doc/Pacemaker_Development/en-US/Ch-Coding.txt index 0812b630a5..188830e2df 100644 --- a/doc/Pacemaker_Development/en-US/Ch-Coding.txt +++ b/doc/Pacemaker_Development/en-US/Ch-Coding.txt @@ -1,164 +1,192 @@ = C Coding Guidelines = //// We prefer [[ch-NAME]], but older versions of asciidoc don't deal well with that construct for chapter headings //// anchor:ch-c-coding[Chapter 2, C Coding Guidelines] +== C Boilerplate == + +indexterm:[C,boilerplate] +indexterm:[licensing,C boilerplate] + +Every C file should start like this: + +==== +[source,C] +---- +/* + * Copyright (C) Andrew Beekhof + * + * This source code is licensed under WITHOUT ANY WARRANTY. + */ +---- +==== + +++ is the year the code was 'originally' created (it is the most +important date for copyright purposes, as it establishes priority and +the point from which expiration is calculated). If the code is modified +in later years, add +-YYYY+ with the most recent year of modification. + +++ should follow the policy set forth in the +https://github.com/ClusterLabs/pacemaker/blob/master/COPYING[+COPYING+] file, +generally one of "GNU General Public License version 2 or later (GPLv2+)" +or "GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)". + == Formatting == === Whitespace === indexterm:[C,whitespace] - Indentation must be 4 spaces, no tabs. - Do not leave trailing whitespace. === Line Length === - Lines should be no longer than 80 characters unless limiting line length significantly impacts readability. === Pointers === indexterm:[C,pointers] - The +*+ goes by the variable name, not the type: ==== [source,C] ---- char *foo; ---- ==== - Use a space before the +*+ and after the closing parenthesis in a cast: ==== [source,C] ---- char *foo = (char *) bar; ---- ==== === Functions === indexterm:[C,functions] - In the function definition, put the return type on its own line, and place the opening brace by itself on a line: ==== [source,C] ---- static int foo(void) { ---- ==== - For functions with enough arguments that they must break to the next line, align arguments with the first argument: ==== [source,C] ---- static int function_name(int bar, const char *a, const char *b, const char *c, const char *d) { ---- ==== - If a function name gets really long, start the arguments on their own line with 8 spaces of indentation: ==== [source,C] ---- static int really_really_long_function_name_this_is_getting_silly_now( int bar, const char *a, const char *b, const char *c, const char *d) { ---- ==== === Control Statements (if, else, while, for, switch) === - The keyword is followed by one space, then left parenthesis without space, condition, right parenthesis, space, opening bracket on the same line. +else+ and +else if+ are on the same line with the ending brace and opening brace, separated by a space: ==== [source,C] ---- if (condition1) { statement1; } else if (condition2) { statement2; } else { statement3; } ---- ==== - In a +switch+ statement, +case+ is indented one level, and the body of each +case+ is indented by another level. The opening brace is on the same line as +switch+. ==== [source,C] ---- switch (expression) { case 0: command1; break; case 1: command2; break; default: command3; } ---- ==== === Operators === indexterm:[C,operators] - Operators have spaces from both sides. Do not rely on operator precedence; use parentheses when mixing operators with different priority. - No space is used after opening parenthesis and before closing parenthesis. ==== [source,C] ---- x = a + b - (c * d); ---- ==== == Naming Conventions == indexterm:[C,naming] - Any exposed symbols in libraries (non-+static+ function names, type names, etc.) must begin with a prefix appropriate to the library, for example, +crm_+, +pe_+, +st_+, +lrm_+. == vim Settings == indexterm:[vim] Developers who use +vim+ to edit source code can add the following settings to their +~/.vimrc+ file to follow Pacemaker C coding guidelines: ---- " follow Pacemaker coding guidelines when editing C source code files filetype plugin indent on au FileType c setlocal expandtab tabstop=4 softtabstop=4 shiftwidth=4 textwidth=80 autocmd BufNewFile,BufRead *.h set filetype=c let c_space_errors = 1 ---- diff --git a/doc/Pacemaker_Development/en-US/Ch-Python.txt b/doc/Pacemaker_Development/en-US/Ch-Python.txt index 1cc6b1c04c..55f8b66c20 100644 --- a/doc/Pacemaker_Development/en-US/Ch-Python.txt +++ b/doc/Pacemaker_Development/en-US/Ch-Python.txt @@ -1,99 +1,135 @@ = Python Coding Guidelines = //// We prefer [[ch-NAME]], but older versions of asciidoc don't deal well with that construct for chapter headings //// anchor:ch-python-coding[Chapter 3, Python Coding Guidelines] -== Python Compatibility == +[[s-python-boilerplate]] +== Python Boilerplate == -indexterm:[python,2] -indexterm:[python,3] -indexterm:[python,versions] +indexterm:[Python,boilerplate] +indexterm:[licensing,Python boilerplate] -Pacemaker targets compatibility with python 2.6 and later, and python 3.2 and -later. These versions have added features to be more compatible with each -other, allowing us to support both the 2 and 3 series with the same code. It is -a good idea to test any changes with both python 2 and 3. - -=== Include in All Python Code === +Every Python file should start like this: ==== [source,Python] ---- -# Pacemaker targets compatibility with python 2.6+ and 3.2+ +[] +""" +""" + +# Pacemaker targets compatibility with Python 2.6+ and 3.2+ from __future__ import print_function, unicode_literals, absolute_import, division + +__copyright__ = "Copyright (C) Andrew Beekhof " +__license__ = " WITHOUT ANY WARRANTY" ---- ==== -That means: +If the file is meant to be directly executed, the first line (++) +should be +#!/usr/bin/python+. If it is meant to be imported, omit this line. + +++ is obviously a brief description of the file's +purpose. The string may contain any other information typically used in +a Python file https://www.python.org/dev/peps/pep-0257/[docstring]. + +The +import+ statement is discussed further in <>. + +++ is the year the code was 'originally' created (it is the most +important date for copyright purposes, as it establishes priority and +the point from which expiration is calculated). If the code is modified +in later years, add +-YYYY+ with the most recent year of modification. + +++ should follow the policy set forth in the +https://github.com/ClusterLabs/pacemaker/blob/master/COPYING[+COPYING+] file, +generally one of "GNU General Public License version 2 or later (GPLv2+)" +or "GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)". + + +== Python Compatibility == + +indexterm:[Python,2] +indexterm:[Python,3] +indexterm:[Python,versions] + +Pacemaker targets compatibility with Python 2.6 and later, and Python 3.2 and +later. These versions have added features to be more compatible with each +other, allowing us to support both the 2 and 3 series with the same code. It is +a good idea to test any changes with both Python 2 and 3. + +[[s-python-future-imports]] +=== Python Future Imports === + +The future imports used in <> mean: * All print statements must use parentheses, and printing without a newline is accomplished with the +end=' '+ parameter rather than a trailing comma. * All string literals will be treated as Unicode (the +u+ prefix is unnecessary, and must not be used, because it is not available in Python 3.2). * Local modules must be imported using +from . import+ (rather than just +import+). To import one item from a local module, use +from .modulename import+ (rather than +from modulename import+). * Division using +/+ will always return a floating-point result (use +//+ if you want the integer floor instead). === Other Python Compatibility Requirements === * When specifying an exception variable, always use +as+ instead of a comma (e.g. +except Exception as e+ or +except (TypeError, IOError) as e+). Use +e.args+ to access the error arguments (instead of iterating over or subscripting +e+). * Use +in+ (not +has_key()+) to determine if a dictionary has a particular key. * Always use the I/O functions from the +io+ module rather than the native I/O functions (e.g. +io.open()+ rather than +open()+). * When opening a file, always use the +t+ (text) or +b+ (binary) mode flag. * Be aware of the bytes type added in Python 3. Many places where strings are used in Python 2 use bytes or bytearrays in Python 3 (for example, the pipes used with +subprocess.Popen()+). Code should handle both possibilities. * Be aware that the +items()+, +keys()+, and +values()+ methods of dictionaries return lists in Python 2 and views in Python 3. In many case, no special handling is required, but if the code needs to use list methods on the result, cast the result to list first. * Do not name variables +with+ or +as+. * Do not raise or catch strings as exceptions (e.g. +raise "Bad thing"+). * Do not use the +cmp+ parameter of sorting functions (use +key+ instead, if needed) or the +$$__cmp__()$$+ method of classes (implement rich comparison methods such as +$$__lt__()$$+ instead, if needed). * Do not use the +buffer+ type. * Do not use features not available in all targeted Python versions. Common examples include: ** The +argparse+, +html+, +ipaddress+, +sysconfig+, and +UserDict+ modules ** The +collections.OrderedDict+ class ** The +subprocess.run()+ function ** The +subprocess.DEVNULL+ constant ** +subprocess+ module-specific exceptions ** Set literals (+{1, 2, 3}+) === Python Usages to Avoid === Avoid the following if possible, otherwise research the compatibility issues involved (hacky workarounds are often available): * long integers * octal integer literals * mixed binary and string data in one data file or variable * metaclasses * +locale.strcoll+ and +locale.strxfrm+ * the +configparser+ and +ConfigParser+ modules * importing compatibility modules such as +six+ (so we don't have to add them to Pacemaker's dependencies) == Formatting Python Code == indexterm:[Python,formatting] * Indentation must be 4 spaces, no tabs. * Do not leave trailing whitespace. * Lines should be no longer than 80 characters unless limiting line length significantly impacts readability. For Python, this limitation is flexible since breaking a line often impacts readability, but definitely keep it under 120 characters. * Where not conflicting with this style guide, it is recommended (but not required) to follow https://www.python.org/dev/peps/pep-0008/:[PEP 8]. diff --git a/doc/Pacemaker_Development/en-US/Revision_History.xml b/doc/Pacemaker_Development/en-US/Revision_History.xml index fcf382dcbf..d1ea73cdc6 100644 --- a/doc/Pacemaker_Development/en-US/Revision_History.xml +++ b/doc/Pacemaker_Development/en-US/Revision_History.xml @@ -1,40 +1,40 @@ %BOOK_ENTITIES; ]> Revision History 1-0 Tue Jul 26 2016 KenGaillot kgaillot@redhat.com Convert coding guidelines and developer FAQ to Publican document 1-1 Wed Aug 17 2016 KenGaillot kgaillot@redhat.com - Add chapter for python coding - guidelines + Add Python coding guidelines, and + more about licensing