Coding Standards » History » Version 14

Tom Morris, 12/22/2016 06:39 PM

1 1 Tom Clegg
h1. Coding Standards
2 1 Tom Clegg
3 3 Tom Clegg
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.
4 1 Tom Clegg
5 2 Tom Clegg
{{toc}}
6 1 Tom Clegg
7 2 Tom Clegg
h2. Git commits
8 2 Tom Clegg
9 1 Tom Clegg
Make sure your name and email address are correct.
10 1 Tom Clegg
11 1 Tom Clegg
* Use @git config --global user.email foo@example.com@ et al.
12 1 Tom Clegg
* 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!
13 1 Tom Clegg
14 9 Tom Clegg
Refer to a story number in each commit comment.
15 9 Tom Clegg
16 9 Tom Clegg
* @1234: Remove useless button.@
17 9 Tom Clegg
18 9 Tom Clegg
*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.
19 9 Tom Clegg
20 9 Tom Clegg
* @closes #1234@, or
21 9 Tom Clegg
* @refs #1234@
22 9 Tom Clegg
23 1 Tom Clegg
Use descriptive commit comments.
24 1 Tom Clegg
25 1 Tom Clegg
* Describe the delta between the old and new tree. If possible, describe the delta in *behavior* rather than the source code itself.
26 9 Tom Clegg
* Good: "1234: Support use of spaces in filenames."
27 9 Tom Clegg
* Good: "1234: Fix crash when user_id is nil."
28 1 Tom Clegg
* Less good: "Add some controller methods." (What do they do?)
29 1 Tom Clegg
* Less good: "More progress on UI branch." (What is different?)
30 1 Tom Clegg
* Less good: "Incorporate Tom's suggestions." (Who cares whose suggestions -- what changed?)
31 1 Tom Clegg
32 1 Tom Clegg
If further background or explanation is needed, separate it from the summary with a blank line.
33 1 Tom Clegg
34 1 Tom Clegg
* Example: "Users found it confusing that the boxes had different colors even though they represented the same kinds of things."
35 1 Tom Clegg
36 13 Tom Clegg
h2. Source code formatting
37 1 Tom Clegg
38 13 Tom Clegg
(Unless otherwise specified by style guide...)
39 13 Tom Clegg
40 10 Tom Clegg
No TAB characters in source files. "Except go programs.":https://golang.org/cmd/gofmt/
41 1 Tom Clegg
42 6 Tom Clegg
* Emacs: add to @~/.emacs@ → @(setq-default indent-tabs-mode nil)@
43 6 Tom Clegg
* Vim: add to @~/.vimrc@ → @:set expandtab@
44 8 Tom Clegg
* See [[Coding Standards#Git setup|Git setup]] below
45 4 Ward Vandewege
46 6 Tom Clegg
No inline comments: @this = !desired; # we don't want to do it.@
47 4 Ward Vandewege
48 6 Tom Clegg
No long (>80 column) lines, except in rare cases when the alternative is really clunky.
49 6 Tom Clegg
50 4 Ward Vandewege
No whitespace at the end of lines. Make git-diff show you:
51 5 Ward Vandewege
52 5 Ward Vandewege
  git config color.diff.whitespace "red reverse"
53 6 Tom Clegg
git diff --check
54 1 Tom Clegg
55 13 Tom Clegg
h2. What to include
56 13 Tom Clegg
57 1 Tom Clegg
No commented-out blocks of code that have been replaced or obsoleted.
58 1 Tom Clegg
59 1 Tom Clegg
* It is in the git history if we want it back.
60 1 Tom Clegg
* 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.
61 1 Tom Clegg
62 1 Tom Clegg
No commented-out debug statements.
63 1 Tom Clegg
64 1 Tom Clegg
* 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"@
65 1 Tom Clegg
66 13 Tom Clegg
h2. Style mismatch
67 13 Tom Clegg
68 1 Tom Clegg
Adopt indentation style of surrounding lines or (when starting a new file) the nearest existing source code in this tree/language.
69 1 Tom Clegg
70 1 Tom Clegg
If you fix up existing indentation/formatting, do that in a separate commit.
71 1 Tom Clegg
* If you bundle formatting changes with functional changes, it makes functional changes hard to find in the diff.
72 1 Tom Clegg
73 13 Tom Clegg
h2. Go
74 13 Tom Clegg
75 13 Tom Clegg
gofmt, golint, etc., and https://github.com/golang/go/wiki/CodeReviewComments
76 13 Tom Clegg
77 13 Tom Clegg
h2. Ruby
78 13 Tom Clegg
79 13 Tom Clegg
https://github.com/bbatsov/ruby-style-guide
80 13 Tom Clegg
81 1 Tom Clegg
h2. Python
82 13 Tom Clegg
83 13 Tom Clegg
PEP-8.
84 12 Tom Clegg
85 12 Tom Clegg
Tell Emacs you don't want a blank line at the end of a multiline docstring.
86 12 Tom Clegg
87 12 Tom Clegg
    (setq python-fill-docstring-style 'pep-257-nn)
88 12 Tom Clegg
89 11 Brett Smith
h2. JavaScript
90 11 Brett Smith
91 14 Tom Morris
"Always use 3 equals unless you have a good reason to use 2."https://github.com/airbnb/javascript#comparison--eqeqeq
92 14 Tom Morris
"Use 2 spaces for indents":https://github.com/airbnb/javascript#whitespace--spaces
93 14 Tom Morris
94 14 Tom Morris
Follow the Airbnb Javascript coding style guide unless otherwise stated (the rules above are for emphasis, not exceptions)
95 14 Tom Morris
https://github.com/airbnb/javascript
96 14 Tom Morris
97 11 Brett Smith
98 7 Tom Clegg
h2. Git setup
99 6 Tom Clegg
100 7 Tom Clegg
Configure git to prevent you from committing whitespace errors.
101 1 Tom Clegg
102 6 Tom Clegg
<pre>
103 7 Tom Clegg
git config --global core.whitespace tab-in-indent,trailing-space
104 7 Tom Clegg
git config --global apply.whitespace error
105 6 Tom Clegg
</pre>