blob: b4e183283229d11826a46f9f81aa714d1d132218 [file] [log] [blame]
mbligh71d338a2007-10-08 05:05:50 +00001These rules are fairly standard and boring. People will bitch about something
2in here, no doubt. Get over it. Much of this was stolen from the Linux Kernel
3coding style, because most of it makes good sense. If you disagree, that's OK,
4but please stick to the rules anyway ;-)
5
6
7Language
8
9Please use Python where possible. It's not the ideal language for everything,
10but it's pretty good, and consistency goes a long way in making the project
11maintainable. (Obviously using C or whatever for writing tests is fine).
12
13
14Indentation & whitespace
15
16Format your code for an 80 character wide screen.
17
18Indentation is hard tabs, equivalent to 8 spaces. Yes, I know that's pretty
19large, but especially in Python where code flow is controlled by indentation
20levels, it's critical for it to be clearly visibile.
21
22People will claim that doesn't allow them enough levels of indentation on an
2380 character screen - they need to fix their code instead: use smaller
24functions, and more local variables - it makes the code so much easier to read.
25
26Don't leave trailing whitespace, or put whitespace on blank lines.
27Leave TWO blank lines between functions - this is Python, there are no clear
28function end markers, and we need help.
29
30
31Variable names and UpPeR cAsE
32
33Use descriptive variable names where possible - it helps to make the code
34self documenting.
35
36Don't use CamelCaps style in most places - use underscores to separate parts
37of your variable_names please. I shall make a bedgrudging exception for class
38names I suppose, but I'll still whine about it a lot.
39
40
41Comments
42
43Generally, you want your comments to tell WHAT your code does, not HOW.
44We can figure out how from the code itself (or if not, your code needs fixing).
45
46Try to describle the intent of a function and what it does in a triple-quoted
47(multiline) string just after the def line. We've tried to do that in most
48places, though undoubtedly we're not perfect. A high level overview is
49incredibly helpful in understanding code.
50
51
52Simple code
53
54Keep it simple; this is not the right place to show how smart you are. We
55have plenty of system failures to deal with without having to spend ages
56figuring out your code, thanks ;-) Readbility, readability, readability.
57I really don't care if other things are more compact.
58
59"Debugging is twice as hard as writing the code in the first place. Therefore,
60if you write the code as cleverly as possible, you are, by definition, not
61smart enough to debug it." Brian Kernighan
62
63
64Function length
65
66Please keep functions short, under 30 lines or so if possible. Even though
67you are amazingly clever, and can cope with it, the rest of us are all stupid,
68so be nice and help us out. To quote the Linux Kernel coding style:
69
70Functions should be short and sweet, and do just one thing. They should
71fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
72as we all know), and do one thing and do that well.
73
74
mbligh900b6c12008-01-14 16:56:47 +000075Exceptions
76
77When raising exceptions, the preferred syntax for it is:
78
79raise FooException('Exception Message')
80
81Please don't raise string exceptions, as they're deprecated and will be removed
82from future versions of python. If you're in doubt about what type of exception
83you will raise, please look at http://docs.python.org/lib/module-exceptions.html
84and client/common_lib/error.py, the former is a list of python built in
85exceptions and the later is a list of autotest/autoserv internal exceptions. Of
86course, if you really need to, you can extend the exception definitions on
87client/common_lib/error.py.
88
89
mbligh71d338a2007-10-08 05:05:50 +000090Submitting patches
91
92Generate universal diffs. Email them to autotest@test.kernel.org.
93Most mailers now break lines and/or changes tabs to spaces. If you know how
94to avoid that - great, put your patches inline. If you're not sure, just
95attatch them, I don't care much. Please base them off the current version.
96
97Don't worry about submitting patches to a public list - everybody makes
98mistakes, especially me ... so get over it and don't worry about it.
99(though do give your changes a test first ;-))