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 For hanging indentation, use 8 spaces plus all args should be on the new line.
28
29      # Either of the following hanging indentation is considered acceptable.
30 YES: return 'class: %s, host: %s, args = %s' % (
31              self.__class__.__name__, self.hostname, self.args)
32
33 YES: return 'class: %s, host: %s, args = %s' % (
34              self.__class__.__name__,
35              self.hostname,
36              self.args)
37
38      # Do not use 4 spaces for hanging indentation
39 NO:  return 'class: %s, host: %s, args = %s' % (
40          self.__class__.__name__, self.hostname, self.args)
41
42      # Do put all args on new line
43 NO:  return 'class: %s, host: %s, args = %s' % (self.__class__.__name__,
44              self.hostname, self.args)
45
46 Don't leave trailing whitespace, or put whitespace on blank lines.
47
48 Leave TWO blank lines between functions - this is Python, there are no clear
49 function end markers, and we need help.
50
51
52 Variable names and UpPeR cAsE
53
54 Use descriptive variable names where possible - it helps to make the code
55 self documenting.
56
57 Don't use CamelCaps style in most places - use underscores to separate parts
58 of your variable_names please. I shall make a bedgrudging exception for class
59 names I suppose, but I'll still whine about it a lot.
60
61
62 Importing modules
63
64 The order of imports should be as follows:
65
66 Standard python modules
67 Non-standard python modules
68 Autotest modules
69
70 Within one of these three sections, all module imports using the from
71 keyword should appear after regular imports.
72 Modules should be lumped together on the same line.
73 Wildcard imports (from x import *) should be avoided if possible.
74 Classes should not be imported from modules, but modules may be imported
75  from packages, i.e.:
76 from common_lib import error
77 and not
78 from common_lib.error import AutoservError
79
80 For example:
81 import os, pickle, random, re, select, shutil, signal, StringIO, subprocess
82 import sys, time, urllib, urlparse
83 import common   # Magic autotest_lib module and sys.path setup code.
84 import MySQLdb  # After common so that we check our site-packages first.
85 from common_lib import error
86
87 Testing None
88
89 Use "is None" rather than "== None" and "is not None" rather than "!= None".
90 This way you'll never run into a case where someone's __eq__ or __ne__
91 method do the wrong thing
92
93
94 Comments
95
96 Generally, you want your comments to tell WHAT your code does, not HOW.
97 We can figure out how from the code itself (or if not, your code needs fixing).
98
99 Try to describle the intent of a function and what it does in a triple-quoted
100 (multiline) string just after the def line. We've tried to do that in most
101 places, though undoubtedly we're not perfect. A high level overview is
102 incredibly helpful in understanding code.
103
104
105 Hardcoded String Formatting
106
107 Strings should use only single quotes for hardcoded strings in the code. Double
108 quotes are acceptable when single quote is used as part of the string.
109 Multiline string should not use '\' but wrap the string using parenthesises.
110
111 REALLY_LONG_STRING = ('This is supposed to be a really long string that is '
112                       'over 80 characters and does not use a slash to '
113                       'continue.')
114
115 Docstrings
116
117 Docstrings are important to keep our code self documenting. While it's not
118 necessary to overdo documentation, we ask you to be sensible and document any
119 nontrivial function. When creating docstrings, please add a newline at the
120 beginning of your triple quoted string and another newline at the end of it. If
121 the docstring has multiple lines, please include a short summary line followed
122 by a blank line before continuing with the rest of the description. Please
123 capitalize and punctuate accordingly the sentences. If the description has
124 multiple lines, put two levels of indentation before proceeding with text. An
125 example docstring:
126
127 def foo(param1, param2):
128     """
129     Summary line.
130
131     Long description of method foo.
132
133     @param param1: A thing called param1 that is used for a bunch of stuff
134             that has methods bar() and baz() which raise SpamError if
135             something goes awry.
136
137     @returns a list of integers describing changes in a source tree
138
139     @raises exception that could be raised if a certain condition occurs.
140
141     """
142
143 The tags that you can put inside your docstring are tags recognized by systems
144 like doxygen. Not all places need all tags defined, so choose them wisely while
145 writing code. Generally (if applicable) always list parameters, return value
146 (if there is one), and exceptions that can be raised to each docstring.
147
148 @author - Code author
149 @param - Parameter description
150 @raise - If the function can throw an exception, this tag documents the
151 possible exception types.
152 @raises - same as @raise.
153 @return - Return value description
154 @returns - Same as @return
155 @see - Reference to what you have done
156 @warning - Call attention to potential problems with the code
157 @var -  Documentation for a variable or enum value (either global or as a
158 member of a class)
159 @version - Version string
160
161 When in doubt refer to: http://doxygen.nl/commands.html
162
163 Simple code
164
165 Keep it simple; this is not the right place to show how smart you are. We
166 have plenty of system failures to deal with without having to spend ages
167 figuring out your code, thanks ;-) Readbility, readability, readability.
168 I really don't care if other things are more compact.
169
170 "Debugging is twice as hard as writing the code in the first place. Therefore,
171 if you write the code as cleverly as possible, you are, by definition, not
172 smart enough to debug it."  Brian Kernighan
173
174
175 Function length
176
177 Please keep functions short, under 30 lines or so if possible. Even though
178 you are amazingly clever, and can cope with it, the rest of us are all stupid,
179 so be nice and help us out. To quote the Linux Kernel coding style:
180
181 Functions should be short and sweet, and do just one thing.  They should
182 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
183 as we all know), and do one thing and do that well.
184
185
186 Exceptions
187
188 When raising exceptions, the preferred syntax for it is:
189
190 raise FooException('Exception Message')
191
192 Please don't raise string exceptions, as they're deprecated and will be removed
193 from future versions of python. If you're in doubt about what type of exception
194 you will raise, please look at http://docs.python.org/lib/module-exceptions.html
195 and client/common_lib/error.py, the former is a list of python built in
196 exceptions and the later is a list of autotest/autoserv internal exceptions. Of
197 course, if you really need to, you can extend the exception definitions on
198 client/common_lib/error.py.
199
200
201 Submitting patches
202
203 Generate universal diffs. Email them to autotest@test.kernel.org.
204 Most mailers now break lines and/or changes tabs to spaces. If you know how
205 to avoid that - great, put your patches inline. If you're not sure, just
206 attatch them, I don't care much. Please base them off the current version.
207
208 Don't worry about submitting patches to a public list - everybody makes
209 mistakes, especially me ... so get over it and don't worry about it.
210 (though do give your changes a test first ;-))