diff options
| -rw-r--r-- | CODING.md | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/CODING.md b/CODING.md new file mode 100644 index 000000000..fbd1b2de2 --- /dev/null +++ b/CODING.md @@ -0,0 +1,139 @@ +# UHD Coding Standards + +Note: This file applies to all code within the UHD repository, not just for +code that is actually part of the UHD library. + +## Preamble + +To quote R. W. Emerson: "A foolish consistency is the hobgoblin of little minds, +adored by little statesmen and philosophers and divines". Ignoring the little +statesmen for a minute, these coding standards are here to make our life +*easier*, not simply add additional rules. They are meant as additional guidance +for developers, and are not meant to be interpreted as law. + +So, ultimately, it is up to the developer to decide how much these guidelines +should be heeded when writing code, and up to reviewers how much they are +relevant to new submissions. +That said, a consistent codebase is easier to maintain, read, understand, and +extend. Choosing personal preferences over these coding guidelines is not a +helpful move for the team and future maintainability of the UHD codebase. + +## General Coding Guidelines + +* Never submit code with trailing whitespace. +* Code layout: We use 4 spaces for indentation levels, and never tabs. +* Code is read more often than it's written. Code readability is thus something + worth optimizing for. +* Try and keep line lengths to 79 characters, unless readability suffers. We + often have to do fun things like SSH into machines and edit code in a + terminal, and do side-by-side views of code on small-ish screens, so this is + actually pretty helpful. +* Go crazy with log messages. Trace-level log messages in particular can be + used copiously and freely (unless in rare cases where the can interfere with + performance). Note that in C++, we have the option of fully compiling out + trace-level messages (and even higher levels). + +## C++-specific Guidelines + +* Use Doxygen doc-blocks copiously. +* All things equal, prefer standard C++ constructs over Boost constructs (see + also Boost guidelines). +* Given the option, prefer C++ lambdas over std::bind, and just don't use + boost::bind if you can. +* `size_t` is the correct container for all indexing of C++ structures (such + as vectors). But keep in mind that the size of `size_t` is + *platform-dependent*! +* Use size-specific types whenever interacting with hardware (`int32_t`, etc.). + It's very easy to get bitten by incorrect sizes. +* Include include files in the following order: Local headers, other + UHD headers, 3rd-party library headers, Boost headers, standard headers. + The rationale is to include from most to least specific. This is the best way + to catch missing includes (if you were to include the standard header first, + it would be available to all include files that come later. If they need that + standard header too, they should be including it themselves). + Example: + +```cpp +#include "x300_specific.hpp" +#include <uhd/utils/log.hpp> +#include <libusb/foo.hpp> +#include <boost/shared_ptr.hpp> +#include <mutex> +``` + +* Feel free to use modern C/C++ features even if they were not used before. + Make sure they work with the compilers and dependencies which are set for the + version of UHD the commit will be made upon. The Ettus CI system will be able + to confirm this. + For interesting new features, use 'anchor commits', which describe clearly + which new feature was used. They can be used as a reference for other + developers. Example: + +``` +commit 9fe731cc371efee7f0051186697e611571c5b41b +Author: Andrej Rode <andrej.rode@ettus.com> +Date: Tue Nov 22 16:19:38 2016 -0800 + + utils: uhd_find_devices display one device for each unique serial found + + Note: This also is the first precedent for the usage of the 'auto' keyword + in UHD. Commits past this one will also be able to use 'auto'. + + Reviewed-By: Martin Braun <martin.braun@ettus.com> +``` + + +## Boost-specific Guidelines + +* Avoid Boost where possible. +* Don't use Boost's sleep functions. Prefer `std::chrono` functions. +* When using `boost::assign::list_of` or `boost::assign::map_list_of`, make + sure to explicitly cast to the appropriate container (even better: Avoid + `boost::assign`, maybe use std initializer lists where possible): + +```cpp +std::vector<std::string> foo = + boost::assign::list_of<std::string> // Explicitly list the type (in this + ("string1") // case, std::string). Then list all + ("string2") // the items (string1, string2, etc). + ("etc") + .to_container(foo); // Finally, call conversion routine explicitly. +// Same for maps: +std::map<std::string, std::string> bar = + boost::assign::map_list_of<std::string, std::string> + ("a", "b") + ("c", "d") + ("etc", "etc") + .to_container(bar); +``` + + +## Python-specific Guidelines + +* Keep Python code compatible with Py2k and Py3k. There are plenty of tools to + aid with this, such as `futurize`. +* Follow the suggestions in PEP8 (https://www.python.org/dev/peps/pep-0008/) + and PEP257 (https://www.python.org/dev/peps/pep-0257/). The former is about + code layout in general, the latter about docstrings. +* Pylint is good tool for helping with following code guidelines. It's very + fussy though, so don't get too worked up about following its suggestions. + + +## Revision Control Hygiene + +* In this repository, we almost always use fast-forward merges, and no merge + commits. +* Prefix all commit messages with the section of code they apply to (Example: + "x300: Fixed overflow at full moon" +* Keep the subject line of a git commit short and concise (so that + `git log --oneline` is actually useful), and follow up in greater detail in + the body of the commmit message. The body is separated from the subject line + with one blank line. +* Avoid long lines in commit messages (standard is 50 characters for subject, + and 72 characters for body). +* Avoid refactoring, whitespace cleanup, or fixing code to match coding + guidelines in the same commit as modifying behaviour. Prefer dedicated + cleanup commits. +* Remember that we ship git repositories, not just code. This means every + commit is part of our product and should be treated as such. + |