Autotest: Clean up Style Guide
Cleaned up the style guide to make it clearer and fixed a few
incorrect examples.
BUG=None
TEST=None
Change-Id: Ib71431a46bb004e05d6eadd4e9205b25e98d45ad
Reviewed-on: https://gerrit.chromium.org/gerrit/57211
Reviewed-by: Simran Basi <sbasi@chromium.org>
Tested-by: Simran Basi <sbasi@chromium.org>
Commit-Queue: Simran Basi <sbasi@chromium.org>
diff --git a/CODING_STYLE b/CODING_STYLE
index 0fcd091..44ec4bf 100644
--- a/CODING_STYLE
+++ b/CODING_STYLE
@@ -44,6 +44,7 @@
self.hostname, self.args)
Don't leave trailing whitespace, or put whitespace on blank lines.
+
Leave TWO blank lines between functions - this is Python, there are no clear
function end markers, and we need help.
@@ -57,30 +58,6 @@
of your variable_names please. I shall make a bedgrudging exception for class
names I suppose, but I'll still whine about it a lot.
-Importing modules
-
-The order of imports should be as follows:
-
-Standard python modules
-Non-standard python modules
-Autotest modules
-
-Within one of these three sections, all module imports using the from
-keyword should appear after regular imports.
-Modules should be lumped together on the same line.
-Wildcard imports (from x import *) should be avoided if possible.
-Classes should not be imported from modules, but modules may be imported
- from packages, i.e.:
-from common_lib import error
-and not
-from common_lib.error import AutoservError
-
-For example:
-import os, pickle, random, re, select, shutil, signal, StringIO, subprocess
-import sys, time, urllib, urlparse
-import MySQLdb
-from common_lib import error
-
Importing modules
@@ -125,6 +102,16 @@
incredibly helpful in understanding code.
+Hardcoded String Formatting
+
+Strings should use only single quotes for hardcoded strings in the code. Double
+quotes are acceptable when single quote is used as part of the string.
+Multiline string should not use '\' but wrap the string using parenthesises.
+
+REALLY_LONG_STRING = ('This is supposed to be a really long string that is '
+ 'over 80 characters and does not use a slash to '
+ 'continue.')
+
Docstrings
Docstrings are important to keep our code self documenting. While it's not
@@ -146,23 +133,30 @@
@param param1: A thing called param1 that is used for a bunch of stuff
that has methods bar() and baz() which raise SpamError if
something goes awry.
- @return a list of integers describing changes in a source tree
- ...
+
+ @returns a list of integers describing changes in a source tree
+
+ @raises exception that could be raised if a certain condition occurs.
+
"""
The tags that you can put inside your docstring are tags recognized by systems
like doxygen. Not all places need all tags defined, so choose them wisely while
-writing code.
+writing code. Generally (if applicable) always list parameters, return value
+(if there is one), and exceptions that can be raised to each docstring.
@author - Code author
@param - Parameter description
-@return - Return value description
-@see - Reference to what you have done
-@todo - Things that still need to be worked out
-@version - Version string
-@warning - Call attention to potential problems with the code
-@raises - If the function can throw an exception, this tag documents the
+@raise - If the function can throw an exception, this tag documents the
possible exception types.
+@raises - same as @raise.
+@return - Return value description
+@returns - Same as @return
+@see - Reference to what you have done
+@warning - Call attention to potential problems with the code
+@var - Documentation for a variable or enum value (either global or as a
+member of a class)
+@version - Version string
When in doubt refer to: http://doxygen.nl/commands.html