Arvados

h1. Coding Standards

The rules are always up for debate. However, when debate is needed, it should happen outside the source tree. In other words, if the rules are wrong, first debate the rules in IRC etc., then fix the rules, then follow the new rules.

{{toc}}

h2. Git commits

Make sure your name and email address are correct.

* Use @git config --global user.email foo@example.com@ et al.

* It's a little unfortunate to have commits with author @foo@myworkstation.local@ but not bad enough to rewrite history, so fix this before you push!

Refer to a story number in each commit comment.

* @1234: Remove useless button.@

*When merging/committing to master,* refer to the story number in a way Redmine will notice. Redmine will list these commits/merges on the story page itself.

* @closes #1234@, or

* @refs #1234@

Use descriptive commit comments.

* Describe the delta between the old and new tree. If possible, describe the delta in *behavior* rather than the source code itself.

* Good: "1234: Support use of spaces in filenames."

* Good: "1234: Fix crash when user_id is nil."

* Less good: "Add some controller methods." (What do they do?)

* Less good: "More progress on UI branch." (What is different?)

* Less good: "Incorporate Tom's suggestions." (Who cares whose suggestions -- what changed?)

If further background or explanation is needed, separate it from the summary with a blank line.

* Example: "Users found it confusing that the boxes had different colors even though they represented the same kinds of things."

*Every commit* (even merge commits) must have a DCO sign-off. See [[Developer Certificate Of Origin]].

* Example: <code>Arvados-DCO-1.1-Signed-off-by: Joe Smith <joe.smith@example.com></code>

h2. Source code formatting

(Unless otherwise specified by style guide...)

No TAB characters in source files. "Except go programs.":https://golang.org/cmd/gofmt/

* Emacs: add to @~/.emacs@ → @(setq-default indent-tabs-mode nil)@

* Vim: add to @~/.vimrc@ → @:set expandtab@

* See [[Coding Standards#Git setup|Git setup]] below

No inline comments: @this = !desired; # we don't want to do it.@

No long (>80 column) lines, except in rare cases when the alternative is really clunky.

No whitespace at the end of lines. Make git-diff show you:

  git config color.diff.whitespace "red reverse"

git diff --check

h2. What to include

No commented-out blocks of code that have been replaced or obsoleted.

* It is in the git history if we want it back.

* If its absence would confuse someone reading the new code (despite never having read the old code), explain its absence in an English comment. If the old code is really still needed to support the English explanation, then go ahead -- now we know why it's there.

No commented-out debug statements.

* If the debug statements are likely to be needed in the future, use a logging facility that can be enabled at run time. @logger.debug "foo"@

h2. Style mismatch

Adopt indentation style of surrounding lines or (when starting a new file) the nearest existing source code in this tree/language.

If you fix up existing indentation/formatting, do that in a separate commit.

* If you bundle formatting changes with functional changes, it makes functional changes hard to find in the diff.

h2. Go

gofmt, golint, etc., and https://github.com/golang/go/wiki/CodeReviewComments

h2. Ruby

https://github.com/bbatsov/ruby-style-guide

h2. Python

PEP-8.

Tell Emacs you don't want a blank line at the end of a multiline docstring.

    (setq python-fill-docstring-style 'pep-257-nn)

h2. JavaScript

"Always use 3 equals unless you have a good reason to use 2.":https://github.com/airbnb/javascript#comparison--eqeqeq

"Use 2 spaces for indents":https://github.com/airbnb/javascript#whitespace--spaces

Follow the Airbnb Javascript coding style guide unless otherwise stated (the rules above are for emphasis, not exceptions)

https://github.com/airbnb/javascript

h2. Git setup

Configure git to prevent you from committing whitespace errors.

<pre>

git config --global core.whitespace tab-in-indent,trailing-space

git config --global apply.whitespace error

</pre>

Add a DCO sign-off to the default commit message.

<pre>

cd .../arvados

printf '\n\nArvados-DCO-1.1-Signed-off-by: %s <%s>\n' "$(git config user.name)" "$(git config user.email)" >~/.arvados-dco.txt

git config commit.template ~/.arvados-dco.txt

</pre>

Add a DCO sign-off and "refs #xxxx" comment (referencing the issue# in the name of the branch being merged) to the default merge commit message.

<pre>

cd .../arvados

cat >.git/hooks/prepare-commit-message <<'EOF'

#!/bin/sh

case "$2,$3" in

    merge,)

        br=$(head -n1 ${1})

        n=$(echo "${br}" | egrep -o '[0-9]+')

        exec >${1}

        echo "${br}"

        echo

        echo "refs #${n}"

        echo

        echo "Arvados-DCO-1.1-Signed-off-by: ${GIT_AUTHOR_NAME} <${GIT_AUTHOR_EMAIL}>"

        ;;

    *)

        ;;

esac

EOF

chmod +x .git/hooks/prepare-commit-message

</pre>