diff --git a/Code-Style-Guidelines.md b/Code-Style-Guidelines.md index cad9411..356bf9f 100644 --- a/Code-Style-Guidelines.md +++ b/Code-Style-Guidelines.md @@ -21,39 +21,43 @@ When possible, keep methods as small and focused as possible. The public method 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; +``` java +public void process() { + // Do the first thing + int something; + something = 0; - // Do the third thing - int somethingElseAgain; - somethingElseAgain = somethingElse + 2; - } + // 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; - } +``` java +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. @@ -61,8 +65,10 @@ The only exceptions for comments of smaller granularity than class-level should When you want to use class Bar from package foo, there are two possible ways to import it: - import foo.*; - import foo.Bar; +``` java +import foo.*; +import foo.Bar; +``` Please use the latter.