Edition 2
Abstract
Table of Contents
List of Examples
git clone https://github.com/ClusterLabs/pacemaker.git
change-type: affected-code: explanation where change-type should be Fix or Bug for most bug fixes, Feature for new features, Log for changes to log messages or handling, Doc for changes to documentation or comments, or Test for changes in CTS and regression tests. You will sometimes see Low, Med (or Mid) and High used instead for bug fixes, to indicate the severity. The important thing is that only commits with Feature, Fix, Bug, or High will automatically be included in the change log for the next release. The affected-code is the name of the component(s) being changed, for example, controller or libcrmcommon (it’s more free-form, so don’t sweat getting it exact). The explanation briefly describes the change. The git project recommends the entire summary line stay under 50 characters, but more is fine if needed for clarity. Except for the most simple and obvious of changes, the summary should be followed by a blank line and then a longer explanation of why the change was made.
Table of Contents
Example 2.1. Copyright Notice Format
YYYY[-YYYY] the Pacemaker project contributors
YYYY is the year the file was originally published. The original date is important for two reasons: when two entities claim copyright ownership of the same work, the earlier claim generally prevails; and copyright expiration is generally calculated from the original publication date.
[2]
-YYYY with the most recent year of modification. Even though Pacemaker is an ongoing project, copyright notices are about the years of publication of specific content.
Table of Contents
/* * Copyright <YYYY[-YYYY]> the Pacemaker project contributors * * The version control history for this file may have further details. * * This source code is licensed under <LICENSE> WITHOUT ANY WARRANTY. */
<LICENSE> should follow the policy set forth in the 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+)".
#ifndef MY_HEADER_NAME__H # define MY_HEADER_NAME__H // header code here #endif // MY_HEADER_NAME__H
#ifdef __cplusplus extern "C" { #endif /*! * \file * \brief My brief description here * \ingroup core */ // header code here #ifdef __cplusplus } #endif
* goes by the variable name, not the type:
char *foo;
* and after the closing parenthesis in a cast:
char *foo = (char *) bar;
static int function_name(int bar, const char *a, const char *b, const char *c, void (*d)()) {
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) {
else and else if are on the same line with the ending brace and opening brace, separated by a space.
if or while conditionals. This ensures that the developer’s intent is always clear, making code reviews easier and reducing the chance of using assignment where comparison is intended.
a = f(); if (a < 0) { statement1; } else if (some_other_condition) { statement2; } else { statement3; }
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.
switch (expression) { case 0: command1; break; case 1: command2; break; default: command3; }
x = a + b - (c * d);\internal tag in the Doxygen comment.
PCMK_trace_files and PCMK_trace_functions, as well as making detail logs easier to follow.
static function names, type names, etc.) must begin with a prefix appropriate to the library, for example, crm_, pe_, st_, lrm_. This reduces the chance of naming collisions with software linked against the library.
interval_spec, interval_ms, or interval_ms_s instead of interval).
pid_t, time_t, etc.), the safest approach is to use %lld in the format string, and cast the value to (long long).
NULL as an argument to satisfy %s format specifier in logging and more generally printf style functions. When mere <null> string is a sufficient output representation in such case, there is crm_str convenient macro. Ternary operator is an apparent choice otherwise.
REG_NOSUB with regcomp() whenever possible, for efficiency.
regfree() appropriately.
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
Table of Contents
.in extension, and its first line should be:
#!@PYTHON@
""" <BRIEF-DESCRIPTION> """ # Pacemaker targets compatibility with Python 2.7 and 3.2+ from __future__ import print_function, unicode_literals, absolute_import, division __copyright__ = "Copyright <YYYY[-YYYY]> the Pacemaker project contributors" __license__ = "<LICENSE> WITHOUT ANY WARRANTY"
<BRIEF-DESCRIPTION> is obviously a brief description of the file’s purpose. The string may contain any other information typically used in a Python file docstring.
import statement is discussed further in Section 4.2.1, “Python Future Imports”.
<LICENSE> should follow the policy set forth in the 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+)".
end=' ' parameter rather than a trailing comma.
u prefix is unnecessary, and must not be used, because it is not available in Python 3.2).
from . import (rather than just import). To import one item from a local module, use from .modulename import (rather than from modulename import).
/ will always return a floating-point result (use // if you want the integer floor instead).
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).
in (not has_key()) to determine if a dictionary has a particular key.
io module rather than the native I/O functions (e.g. io.open() rather than open()).
t (text) or b (binary) mode flag.
class Foo(object): rather than class Foo:)
subprocess.Popen()). Code should handle both possibilities.
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.
raise "Bad thing").
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).
buffer type.
html, ipaddress, and UserDict modules
subprocess.run() function
subprocess.DEVNULL constant
subprocess module-specific exceptions
locale.strcoll and locale.strxfrm
configparser and ConfigParser modules
six (so we don’t have to add them to Pacemaker’s dependencies)
pylint --disable=line-too-long,too-many-lines,too-many-instance-attributes,too-many-arguments,too-many-statements produces minimal complaints (even better if you don’t need to disable all those checks).
Table of Contents
git blame and git log scenarios, so some more massive ones may be stated as well.
Table of Contents
extra/gdb/gdbhelpers file, which you can make available in the debugging session easily when invoking it as gdb -x <path-to-gdbhelpers> ....
pcmk command that will guide you regarding other helper functions available, so we won’t replicate that here.
maint/mocked; for instance, based-notifyfenced.c module of based.c skeleton mocking pacemaker-based daemon was exactly to fulfill investigation helper role (the case at hand was also an impulse to kick off this very sort of maintenance support material, to begin with).
| Revision History | |||
|---|---|---|---|
| Revision 1-0 | Tue Jul 26 2016 | , | |
| |||
| Revision 1-1 | Mon Aug 29 2016 | ||
| |||
| Revision 2-0 | Fri Jan 12 2018 | ||
| |||
| Revision 2-1 | Tue Sep 18 2018 | ||
| |||
| Revision 2-2 | Fri Dec 7 2018 | ||
| |||
| Revision 2-3 | Mon May 13 2019 | , | |
| |||
| Revision 2-4 | Fri 17 May 2019 | ||
| |||
| Revision 2-5 | Thu 5 Mar 2020 | ||
| |||