Coding guidelines and code review checklist

This document is for anyone who want to contribute code to the khmer project, and describes our coding standards and code review checklist.

---

Coding standards

All plain-text files should have line widths of 80 characters or less unless that is not supported for the particular file format.

For C++, we use Todd Hoff’s coding standard, and astyle -A10 / “One True Brace Style” indentation and bracing. Note: @CTB needs Emacs settings that work for this.

Vim users may want to set the ARTISTIC_STYLE_OPTIONS shell variable to “-A10 –max-code-length=80” and run `:%!astyle` to reformat. The four space indentation can be set with:

set expandtab
set shiftwidth=4
set softtabstop=4

For Python, PEP 8 is our standard. The `pep8` and `autopep8` Makefile targets are helpful.

Code, scripts, and documentation must have its spelling checked. Vim users can run:

:setlocal spell spelllang=en_us

Use ]s and [s to navigate between misspellings and z= to suggest a correctly spelled word. zg will add a word as a good word.

GNU aspell can also be used to check the spelling in a single file:

aspell check --mode ccpp $filename

Code Review

Please read 11 Best Practices for Peer Code Review.

See also Code reviews: the lab meeting for code and the PyCogent coding guidelines.

Checklist

Copy and paste the following into a pull request comment when it is ready for review:

- [ ] Is it mergable
- [ ] Did it pass the tests?
- [ ] If it introduces new functionality in scripts/ is it tested?
  Check for code coverage.
- [ ] Is it well formatted? Look at `pep8`/`pylint`, `cppcheck`, and
  `make doc` output. Use `autopep8` and `astyle -A10 --max-code-length=80`
  if needed.
- [ ] Is it documented in the ChangeLog?
- [ ] Was a spellchecker run on the source code and documentation after changes
  were made?

Note that after you submit the comment you can check and uncheck the individual boxes on the formatted comment; no need to put x or y in the middle.

comments powered by Disqus