firmware_TouchMTB: print metrics with missing values
[chromiumos/third_party/autotest.git] / CODING_STYLE
1 These rules are fairly standard and boring. People will bitch about something
2 in here, no doubt. Get over it. Much of this was stolen from the Linux Kernel
3 coding style, because most of it makes good sense. If you disagree, that's OK,
4 but please stick to the rules anyway ;-)
5
6
7 Language
8
9 Please use Python where possible. It's not the ideal language for everything,
10 but it's pretty good, and consistency goes a long way in making the project
11 maintainable. (Obviously using C or whatever for writing tests is fine).
12
13
14 Base coding style
15
16 When writing python code, unless otherwise stated, stick to the python style
17 guide (http://www.python.org/dev/peps/pep-0008/).
18
19
20 Indentation & whitespace
21
22 Format your code for an 80 character wide screen.
23
24 Indentation is now 4 spaces, as opposed to hard tabs (which it used to be).
25 This is the Python standard.
26
27 Don't leave trailing whitespace, or put whitespace on blank lines.
28 Leave TWO blank lines between functions - this is Python, there are no clear
29 function end markers, and we need help.
30
31
32 Variable names and UpPeR cAsE
33
34 Use descriptive variable names where possible - it helps to make the code
35 self documenting.
36
37 Don't use CamelCaps style in most places - use underscores to separate parts
38 of your variable_names please. I shall make a bedgrudging exception for class
39 names I suppose, but I'll still whine about it a lot.
40
41 Importing modules
42
43 The order of imports should be as follows:
44
45 Standard python modules
46 Non-standard python modules
47 Autotest modules
48
49 Within one of these three sections, all module imports using the from
50 keyword should appear after regular imports.
51 Modules should be lumped together on the same line.
52 Wildcard imports (from x import *) should be avoided if possible.
53 Classes should not be imported from modules, but modules may be imported
54  from packages, i.e.:
55 from common_lib import error
56 and not
57 from common_lib.error import AutoservError
58
59 For example:
60 import os, pickle, random, re, select, shutil, signal, StringIO, subprocess
61 import sys, time, urllib, urlparse
62 import MySQLdb
63 from common_lib import error
64
65
66 Importing modules
67
68 The order of imports should be as follows:
69
70 Standard python modules
71 Non-standard python modules
72 Autotest modules
73
74 Within one of these three sections, all module imports using the from
75 keyword should appear after regular imports.
76 Modules should be lumped together on the same line.
77 Wildcard imports (from x import *) should be avoided if possible.
78 Classes should not be imported from modules, but modules may be imported
79  from packages, i.e.:
80 from common_lib import error
81 and not
82 from common_lib.error import AutoservError
83
84 For example:
85 import os, pickle, random, re, select, shutil, signal, StringIO, subprocess
86 import sys, time, urllib, urlparse
87 import common   # Magic autotest_lib module and sys.path setup code.
88 import MySQLdb  # After common so that we check our site-packages first.
89 from common_lib import error
90
91 Testing None
92
93 Use "is None" rather than "== None" and "is not None" rather than "!= None".
94 This way you'll never run into a case where someone's __eq__ or __ne__
95 method do the wrong thing
96
97
98 Comments
99
100 Generally, you want your comments to tell WHAT your code does, not HOW.
101 We can figure out how from the code itself (or if not, your code needs fixing).
102
103 Try to describle the intent of a function and what it does in a triple-quoted
104 (multiline) string just after the def line. We've tried to do that in most
105 places, though undoubtedly we're not perfect. A high level overview is
106 incredibly helpful in understanding code.
107
108
109 Docstrings
110
111 Docstrings are important to keep our code self documenting. While it's not
112 necessary to overdo documentation, we ask you to be sensible and document any
113 nontrivial function. When creating docstrings, please add a newline at the
114 beginning of your triple quoted string and another newline at the end of it. If
115 the docstring has multiple lines, please include a short summary line followed
116 by a blank line before continuing with the rest of the description. Please
117 capitalize and punctuate accordingly the sentences. If the description has
118 multiple lines, put two levels of indentation before proceeding with text. An
119 example docstring:
120
121 def foo(param1, param2):
122     """
123     Summary line.
124
125     Long description of method foo.
126
127     @param param1: A thing called param1 that is used for a bunch of stuff
128             that has methods bar() and baz() which raise SpamError if
129             something goes awry.
130     @return a list of integers describing changes in a source tree
131     ...
132     """
133
134 The tags that you can put inside your docstring are tags recognized by systems
135 like doxygen. Not all places need all tags defined, so choose them wisely while
136 writing code.
137
138 @author - Code author
139 @param - Parameter description
140 @return - Return value description
141 @see - Reference to what you have done
142 @todo - Things that still need to be worked out
143 @version - Version string
144 @warning - Call attention to potential problems with the code
145 @raises - If the function can throw an exception, this tag documents the
146 possible exception types.
147
148 When in doubt refer to: http://doxygen.nl/commands.html
149
150 Simple code
151
152 Keep it simple; this is not the right place to show how smart you are. We
153 have plenty of system failures to deal with without having to spend ages
154 figuring out your code, thanks ;-) Readbility, readability, readability.
155 I really don't care if other things are more compact.
156
157 "Debugging is twice as hard as writing the code in the first place. Therefore,
158 if you write the code as cleverly as possible, you are, by definition, not
159 smart enough to debug it."  Brian Kernighan
160
161
162 Function length
163
164 Please keep functions short, under 30 lines or so if possible. Even though
165 you are amazingly clever, and can cope with it, the rest of us are all stupid,
166 so be nice and help us out. To quote the Linux Kernel coding style:
167
168 Functions should be short and sweet, and do just one thing.  They should
169 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
170 as we all know), and do one thing and do that well.
171
172
173 Exceptions
174
175 When raising exceptions, the preferred syntax for it is:
176
177 raise FooException('Exception Message')
178
179 Please don't raise string exceptions, as they're deprecated and will be removed
180 from future versions of python. If you're in doubt about what type of exception
181 you will raise, please look at http://docs.python.org/lib/module-exceptions.html
182 and client/common_lib/error.py, the former is a list of python built in
183 exceptions and the later is a list of autotest/autoserv internal exceptions. Of
184 course, if you really need to, you can extend the exception definitions on
185 client/common_lib/error.py.
186
187
188 Submitting patches
189
190 Generate universal diffs. Email them to autotest@test.kernel.org.
191 Most mailers now break lines and/or changes tabs to spaces. If you know how
192 to avoid that - great, put your patches inline. If you're not sure, just
193 attatch them, I don't care much. Please base them off the current version.
194
195 Don't worry about submitting patches to a public list - everybody makes
196 mistakes, especially me ... so get over it and don't worry about it.
197 (though do give your changes a test first ;-))