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
<http://www.possibility.com/Cpp/CppCodingStandard.html>`__, and
`astyle -A10 / "One True Brace Style"
<http://astyle.sourceforge.net/astyle.html>`__ 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 <http://www.python.org/dev/peps/pep-0008/>`__ 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
<http://smartbear.com/SmartBear/media/pdfs/WP-CC-11-Best-Practices-of-Peer-Code-Review.pdf>`__.

See also `Code reviews: the lab meeting for code
<http://fperez.org/py4science/code_reviews.html>`__ and
`the PyCogent coding guidelines
<http://pycogent.org/coding_guidelines.html>`__.

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.