can_rcv_msg is now a VC flag (XCC)
[akaros.git] / Documentation / CodingPolicy
1 ROS Development Policies
2 ------------------------------------
3 This document will talk about coding standards, version control, and
4 contribution policies.
5
6 Our coding standard is similar to the Linux kernel style (but with a tabstop of
7 4), so when in doubt, do what they do.
8 - No spaces after the name of a function in a call.  For example,
9   printk("hello") not printk ("hello").
10
11 - Functions that take no arguments are declared f(void) not f().
12
13 - Function names are all lower-case, separated by underscores.
14
15 - One space after commas.  For example foo(x, y, z), not foo(x,y,z);
16
17 - One space after keywords "if", "for", "while", "switch".  For example, if
18   (x) not if(x).
19
20 - Space before braces.  For example, if (x) { not if (x){.
21
22 - For if/while/etc, the opening brace is on the same line as the if.  If you
23   have just one line, no brace is necessary.  If you have an if / else clause,
24   and one of them has braces, put braces on both.  An else line should start
25   with a brace.
26
27 - Beginning-of-line indentation via tabs, not spaces.  Use spaces for
28   additional formatting (such as lining up text when word wrapping).
29
30 - Preprocessor macros are usually upper-case.  Try to avoid using macros
31   unless necessary (I prefer static inlines).
32
33 - Pointer declarations have the * on the variable.  void *x, not void* x.
34
35 - Multi-word names are lower_case_with_underscores.  Keep your names short,
36   especially for local variables.
37
38 - 'Permanent' comments in are C /* ... */ comments.  Only use C++ style (//)
39   for temporary commenting-out, such as if you want to not call a function.
40   If you want to block out large chunks of code, use #if 0 ... #endif
41
42 - In a function definition, the function name shoud NOT start a new line.  Old
43   code incorrectly does this, and should be changed over time.
44  
45 - Feel free to use gotos, especially in functions that have cleanup before
46   they exit, or in other places that enhance readability.
47
48 - 80 characters per line.  When you wrap, try to line things up so they make
49   sense, such as space-indenting so function arguments line up vertically.
50
51 - Do not typedef structs.  You can typedef function pointers when convenient.
52   Keep in mind that typedefs require people to look up the real type when they
53   analyze the code.
54
55 - Try to avoid making lots of separate files or extravagant directory
56   hierarchies.  Keep in mind that people will need to work with and find these
57   files (even via tab completion, it can be a pain).
58
59 Version Control: (git)
60 - Git allows us to do a lot of cool things.  One of its primary purposes is to
61   provide a means for us to review each others code.
62
63 - Do not merge.  You should rebase your commits on top of the latest branch,
64   then do a fast-forward merge.  You need to figure this out before working
65   with the main repo.  Merges can be appropriate, but ask brho first.  If you
66   are new to git, then odds are you should do the rebase/merge approach.
67
68 - Do not commit crappy commits.  Hold on to your commits for a little while
69   before pushing, and if a problem appears in a branch that only you are using,
70   you should go back and amend those commits.  git rebase and git commit
71   --amend are your friend.
72
73 - Do not commit to "share code."  If two people are working on the same code
74   and want to pass code from machine to machine, do not use a real branch from
75   the origin repo.  You can do whatever on your own machines (or even in a
76   temporary branch on the scm machine), but the version of the code submitted
77   to the mainline must not have those crappy commits.
78
79 - Commit messages consist of one short line, followed by an empty line, and
80   then a descriptive message (word wrapped).  Most editors (like vi) will help
81   you with this.
82
83 - Once you've pushed a branch to the origin, you normally should not reset it -
84   if the problem is minor, fix it later.  If you do it right away, it is
85   usually not a big deal.  If you broke the repo, fix it, and you should
86   probably send something to ros-kernel@.
87
88 - You ought to use gitk --all, or a similar program, to help visualize what is
89   going on with the tree.
90
91 - Your commits should be of a reasonable size.  Try to isolate your commits to
92   small, easily verifiable changes.  Each commit must compile, but you don't
93   want to change everything in one commit.  Put another way, one commit that
94   can be decoupled into smaller ones ought to be broken up.
95
96 - Likewise, don't do a commit just to change irrelevant things, such as turning
97   off a printk or adjusting your manager() function (unless there's a good
98   reason).  You just pollute the commit stream.
99
100 Contributing:
101 - Currently, we are not accepting unsolicited, large contributions.  If you
102   have something in mind, contact us and we'll see how we can make it work.
103   If you want your work to be merged, you should check with us before starting
104   a project that may be incompatible with our system and goals.
105
106 - We will accept bug fixes.  Until we sort out the copyrights, if you want us
107   to accept your patch, you'll need to assign your copyright to the Regeants of
108   the University of California, which shouldn't be an issue for an UC Berkeley
109   personnel.
110
111 - Expect your code to be audited by the appropriate subsystem maintainer.
112   Basically, this means that if it is related to the sparc port, you need to
113   make Andrew happy.  Otherwise, you need to make Barret happy.
114
115 - Despite being a research project, we make every effort to do things the
116   proper way.  We are extremely reluctant to allow "ghetto hacks", especially
117   the type that pop up near paper deadlines.  The appropriate way to deal with
118   this is to have a separate branch for all the shameful commits you have, and
119   after your deadlines have passed, you pick and choose which commits to apply
120   to the real branch in a way that does not violate our standards.