Project

General

Profile

Coding Standards » History » Version 6

Tom Clegg, 03/20/2014 03:29 PM

1 1 Tom Clegg
h1. Coding Standards
2
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
9 1 Tom Clegg
Make sure your name and email address are correct.
10
11
* Use @git config --global user.email foo@example.com@ et al.
12
* 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
14
Use descriptive commit comments.
15
16
* Describe the delta between the old and new tree. If possible, describe the delta in *behavior* rather than the source code itself.
17
* Good: "Support use of spaces in filenames."
18
* Good: "Fix crash when user_id is nil."
19
* Less good: "Add some controller methods." (What do they do?)
20
* Less good: "More progress on UI branch." (What is different?)
21
* Less good: "Incorporate Tom's suggestions." (Who cares whose suggestions -- what changed?)
22
23
If further background or explanation is needed, separate it from the summary with a blank line.
24
25
* Example: "Users found it confusing that the boxes had different colors even though they represented the same kinds of things."
26
27
Refer to issues in git commits.
28
29
* Redmine notices "refs #12345" and "closes #12345" and "fixes #12345" in commit messages, and links to the commits from the issue page.
30 2 Tom Clegg
31
h2. Source files
32 1 Tom Clegg
33
No TAB characters in source files.
34
35 6 Tom Clegg
* Emacs: add to @~/.emacs@ → @(setq-default indent-tabs-mode nil)@
36
* Vim: add to @~/.vimrc@ → @:set expandtab@
37 4 Ward Vandewege
38 6 Tom Clegg
No inline comments: @this = !desired; # we don't want to do it.@
39 4 Ward Vandewege
40 6 Tom Clegg
No long (>80 column) lines, except in rare cases when the alternative is really clunky.
41
42 4 Ward Vandewege
No whitespace at the end of lines. Make git-diff show you:
43 5 Ward Vandewege
44
  git config color.diff.whitespace "red reverse"
45 6 Tom Clegg
git diff --check
46 1 Tom Clegg
47
No commented-out blocks of code that have been replaced or obsoleted.
48
49
* It is in the git history if we want it back.
50
* 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.
51
52
No commented-out debug statements.
53
54
* 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"@
55
56
Adopt indentation style of surrounding lines or (when starting a new file) the nearest existing source code in this tree/language.
57
58
If you fix up existing indentation/formatting, do that in a separate commit.
59
60
* If you bundle formatting changes with functional changes, it makes functional changes hard to find in the diff.
61 6 Tom Clegg
62
h2. Git hooks
63
64
Use this in @.git/hooks/pre-commit@ to prevent you from committing whitespace errors.
65
66
<pre>
67
git diff-index --check --cached HEAD --
68
</pre>