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