1 # Coding style for autotest in Chrome OS / Android / Brillo 2 These rules elaborate on, but rarely deviate from PEP-8. When in doubt, go 3 with PEP-8. 4 5 6 ## Language 7 * Use Python where possible 8 * Prefer writing more Python to a smaller amount of shell script in host 9 commands. In practice, the Python tends to be easier to maintain. 10 * Some tests use C/C++ in test dependencies, and this is also ok. 11 12 13 ## Indentation & whitespace 14 15 Format your code for an 80 character wide screen. 16 17 Indentation is 4 spaces, as opposed to hard tabs (which it used to be). 18 This is the Python standard. 19 20 For hanging indentation, use 8 spaces plus all args should be on the new line. 21 22 ``` 23 24 # Either of the following hanging indentation is considered acceptable. 25 YES: return 'class: %s, host: %s, args = %s' % ( 26 self.__class__.__name__, self.hostname, self.args) 27 28 YES: return 'class: %s, host: %s, args = %s' % ( 29 self.__class__.__name__, 30 self.hostname, 31 self.args) 32 33 # Do not use 4 spaces for hanging indentation 34 NO: return 'class: %s, host: %s, args = %s' % ( 35 self.__class__.__name__, self.hostname, self.args) 36 37 # Do put all args on new line 38 NO: return 'class: %s, host: %s, args = %s' % (self.__class__.__name__, 39 self.hostname, self.args) 40 ``` 41 42 Don't leave trailing whitespace, or put whitespace on blank lines. 43 44 45 ## Variable names and UpPeR cAsE 46 * Use descriptive variable names where possible 47 * Use `variable_names_like_this` 48 * Use `method_and_function_names_like_this` 49 * Use `UpperCamelCase` for class names 50 51 52 ## Importing modules 53 54 The order of imports should be as follows: 55 56 * Standard python modules 57 * Non-standard python modules 58 * Autotest modules 59 60 Within one of these three sections, all module imports using the from 61 keyword should appear after regular imports. 62 Each module should be imported on its own line. 63 Do not use Wildcard imports (`from x import *`) if possible. 64 65 Import modules, not classes. For example: 66 67 ``` 68 from common_lib import error 69 70 def foo(): 71 raise error.AutoservError(...) 72 ``` 73 74 and not: 75 76 ``` 77 from common_lib.error import AutoservError 78 ``` 79 80 For example: 81 82 ``` 83 import os 84 import pickle 85 import random 86 import re 87 import select 88 import shutil 89 import signal 90 import subprocess 91 92 import common # Magic autotest_lib module and sys.path setup code. 93 import MySQLdb # After common so that we check our site-packages first. 94 95 from common_lib import error 96 ``` 97 98 ## Testing None 99 100 Use `is None` rather than `== None` and `is not None` rather than `!= None`. 101 This way you'll never run into a case where someone's `__eq__` or `__ne__` 102 method does the wrong thing. 103 104 105 ## Comments 106 107 Generally, you want your comments to tell WHAT your code does, not HOW. 108 We can figure out how from the code itself (or if not, your code needs fixing). 109 110 Try to describle the intent of a function and what it does in a triple-quoted 111 (multiline) string just after the def line. We've tried to do that in most 112 places, though undoubtedly we're not perfect. A high level overview is 113 incredibly helpful in understanding code. 114 115 116 ## Hardcoded String Formatting 117 118 Strings should use only single quotes for hardcoded strings in the code. Double 119 quotes are acceptable when single quote is used as part of the string. 120 Multiline strings should not use '\' but wrap the string using parentheseses. 121 122 ``` 123 REALLY_LONG_STRING = ('This is supposed to be a really long string that is ' 124 'over 80 characters and does not use a slash to ' 125 'continue.') 126 ``` 127 128 ## Docstrings 129 130 Docstrings are important to keep our code self documenting. While it's not 131 necessary to overdo documentation, we ask you to be sensible and document any 132 nontrivial function. When creating docstrings, please add a newline at the 133 beginning of your triple quoted string and another newline at the end of it. If 134 the docstring has multiple lines, please include a short summary line followed 135 by a blank line before continuing with the rest of the description. Please 136 capitalize and punctuate accordingly the sentences. If the description has 137 multiple lines, put two levels of indentation before proceeding with text. An 138 example docstring: 139 140 ``` 141 def foo(param1, param2): 142 """ 143 Summary line. 144 145 Long description of method foo. 146 147 @param param1: A thing called param1 that is used for a bunch of stuff 148 that has methods bar() and baz() which raise SpamError if 149 something goes awry. 150 151 @returns a list of integers describing changes in a source tree 152 153 @raises exception that could be raised if a certain condition occurs. 154 155 """ 156 ``` 157 158 The tags that you can put inside your docstring are tags recognized by systems 159 like doxygen. Not all places need all tags defined, so choose them wisely while 160 writing code. Generally (if applicable) always list parameters, return value 161 (if there is one), and exceptions that can be raised to each docstring. 162 163 | Tag | Description | 164 |----------|------------------------------------------------------------------------------------------| 165 | @author | Code author | 166 | @param | Parameter description | 167 | @raise | If the function can throw an exception, this tag documents the possible exception types. | 168 | @raises | Same as @raise. | 169 | @return | Return value description | 170 | @returns | Same as @return | 171 | @see | Reference to other parts of the codebase. | 172 | @warning | Call attention to potential problems with the code | 173 | @var | Documentation for a variable or enum value (either global or as a member of a class) | 174 | @version | Version string | 175 176 When in doubt refer to: http://doxygen.nl/commands.html 177 178 ## Simple code 179 180 Keep it simple; this is not the right place to show how smart you are. We 181 have plenty of system failures to deal with without having to spend ages 182 figuring out your code, thanks ;-) Readbility, readability, readability. 183 Strongly prefer readability and simplicity over compactness. 184 185 "Debugging is twice as hard as writing the code in the first place. Therefore, 186 if you write the code as cleverly as possible, you are, by definition, not 187 smart enough to debug it." Brian Kernighan 188 189 190 ## Function length 191 192 Please keep functions short, under 30 lines or so if possible. Even though 193 you are amazingly clever, and can cope with it, the rest of us are busy and 194 stupid, so be nice and help us out. To quote the Linux Kernel coding style: 195 196 Functions should be short and sweet, and do just one thing. They should 197 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, 198 as we all know), and do one thing and do that well. 199 200 201 ## Exceptions 202 203 When raising exceptions, the preferred syntax for it is: 204 205 ``` 206 raise FooException('Exception Message') 207 ``` 208 209 Please don't raise string exceptions, as they're deprecated and will be removed 210 from future versions of python. If you're in doubt about what type of exception 211 you will raise, please look at http://docs.python.org/lib/module-exceptions.html 212 and client/common\_lib/error.py, the former is a list of python built in 213 exceptions and the later is a list of autotest/autoserv internal exceptions. Of 214 course, if you really need to, you can extend the exception definitions on 215 client/common\_lib/error.py. 216 217 218 ## Submitting patches 219 220 Submit changes through the Chrome OS gerrit instance. This process is 221 documented on 222 [chromium.org](http://dev.chromium.org/developers/contributing-code). 223
