diff --git a/Code-Style-Guidelines.md b/Code-Style-Guidelines.md new file mode 100644 index 0000000..cad9411 --- /dev/null +++ b/Code-Style-Guidelines.md @@ -0,0 +1,97 @@ +## Indentation + +1. Use spaces instead of tabs. +1. Blocks are 2 spaces. + +## Field Naming Conventions + +1. Please do **not** use "hungarian" notation (instance variable names preceded by an 'm', static variable names preceded by an 's' and so on). +1. Start variable names with a lowercase letter, and use camelCase rather than under_scores. +1. Constants (public/private static final) are ALL_CAPS_WITH_UNDERSCORES. + +## Line Length + +To the greatest extent possible, please wrap lines at 100 characters. + +## Write Short Methods + +When possible, keep methods as small and focused as possible. The public methods of a class should read like a book, and essentially just aggregate the actions of private methods within that class. The private methods of a class should, as much as possible, be written in "functional style" -- meaning that their actions are confined to their local scope and their return value without having any other side effects on instance variables of the class. + +## Comments + +Each class should include a class-level Javadoc comment above the class declaration, describing what the overall purpose of the class is. This should be the **only** comment included in the code. If you find yourself writing a method, and are tempted to include comments on what parts of a method are doing, such as: + + public void process() { + // Do the first thing + int something; + something = 0; + + // Do the second thing + int somethingElse; + somethingElse = something + 1; + + // Do the third thing + int somethingElseAgain; + somethingElseAgain = somethingElse + 2; + } + +...treat this as a sign that your method is not correctly factored. Break each comment block up into its own method, and name each method exactly what you would have written as a comment: + + public void process() { + int result = doTheFirstThing(); + result = doTheSecondThing(result); + result = doTheThirdThing(result); + } + + public int doTheFirstThing() { + return 0; + } + + public int doTheSecondThing(int result) { + return result + 1; + } + + public int doTheThirdThing(int result) { + return result + 2; + } + +The only exceptions for comments of smaller granularity than class-level should be cases where you are doing something exceptionally "clever," such as using a double-dispatch pattern and need to warn the casual reviewer not to factor out callbacks into a base class. + +## Fully Qualify Imports + +When you want to use class Bar from package foo, there are two possible ways to import it: + + import foo.*; + import foo.Bar; + +Please use the latter. + +## Import Order + +The ordering of import statements is: + +1. Android imports +1. Imports from third parties (com, junit, net, org) +1. java and javax + +Within each grouping, the imports should be sorted alphabetically, with capital letters before lower case letters (eg. Z before a). There should be a blank line between each major grouping. + +## Use Annotations + +Specifically, use @Override whenever possible, for clarity. + +## Treat Acronyms As Words + +In variable names and class definitions, try to treat acroynms as words (XmlHttpRequest instead of XMLHTTPRequest, for instance). + +## Be careful what you log! + +Whenever you insert a log statement, please think carefully about whether it could ever possibly leak sensitive information. + +## Copyright Statement + +Every file should have a copyright statement at the top. The package statement and import statements should follow, each block separated by a blank line. + +## Don't use finalizers + +There are no guarantees as to when a finalizer will be called, or if it will be called at all. \ No newline at end of file