Some Style Facts:

    • Good style is...
      • Both an art and a science.
      • Open to some debate, yet mostly agreed upon.
      • The product of years of suffering due to bad style.

    • Good style reduces time spent debugging, and...
      • Around 75% of a developer's time is spent debugging (source)
      • Fixing a bug takes 30 times longer than writing a line of code (source)

    • Good style reduces errors, and...
      • Software errors cost the global economy Billions annually! (source)
      • Software errors have resulted in many spectacular failures (source)

    • Some Style Guides (which are not OUR style guide):

    Java Programming Style

    1. Clarity Rules
      1. Ownership
        You must include your name, date and period in a comment at the top of every file you submit.
        Point error: not writing your name/date/period in a submitted file

      2. Comments
        You should write concise, clear, and informative comments that make your code even easier to understand.
        • Comments should be included with any piece of code that is not self-documenting.
        • Comments should not be written where they are not needed.
        Point error: not writing any comments at all.
        Point error: writing too many or too few comments, or writing bad comments.

        Here is an example comment for a Hello World program from the notes:
        // Dr. Mariano Dec 31, 2021 // Period 6 // Program to print Hello World! public class HelloWorld { public static void main(String[] args) { System.out.println("Hello World!"); } }

      1. Variable Names
        Use meaningful variable and function names (whenever possible).
        • Variables and functions should be written in the camelCase format. In this format, the first letter is in lowercase, and all following words are uppercased (eg: tetrisPiece).
        • For example, some good, meaningful variable names for a graphics problem with a flag might include numStars, numStripes, stripeColor, or stripeWidth.
        • On the other hand, it can be hard to know what variables named a, b, and c do, especially if you haven't written any comments either!
        • Short variable names are ok if it is relatively obvious what they do. For example, cx and cy are commonly use for the center point of a circle, and r is probably the circle's radius.
        • Variable names should not overwrite built-in function names; for example, str is a bad name for a string variable.
          • Common built-in keywords to avoid include dict, dir, id, input, int, len, list, map, max, min, next, object, set, str, sum, and type.
        Point error: not having any meaningful variable names (assuming variables are used).
        Point error: using some non-meaningful variable names.
        • Exceptions: i/j for index/iterator, c for character, s for string, and n/x/y for number.
        Point error: not using camelCase formatting.
        Point error: using a built-in function name as a variable.

      2. Unused Code
        Your code should not include any dead code (code that will never be executed).
        • Additionally, all debugging code should be removed once your program is complete, even if it has been commented out.
        Points error: having any dead or debugging code.

      3. Formatting
        Your code formatting should make your code readable. This includes:
        • Not exceeding 80 characters in any one line (including comments!).
        • Indenting consistently. Use spaces, not tabs, with 4 spaces per indent level (most editors let you map tabs to spaces automatically).
        • Using consistent whitespace throughout your code.
          • Good whitespace: x=y+2, x = y+2, or x = y + 2
          • Bad whitespace: x= y+2, x = y +2, or x = y   + 2
        Point error: having bad formatting in any of the ways described above.

    1. Robustness Rules
      1. Efficiency
        In general, your code should be reasonably efficient.
        • As this is an introductory course, I do not expect you to write the most efficient solutions generally. However, your code may not be "grossly" inefficient, especially if you had simple, clear, and reasonably efficient options to choose from.
        Point error: writing a function that works correctly but takes more than 30 seconds to test (with some exceptions).
        Point error: writing a function that works correctly but takes more than 5 seconds to test (with some exceptions).

      2. Repetitive Code
        In general, you should not have repetitive code.
        • One example of this is duplicate code, code that has been copy-pasted. This should instead be put into a helper function.
        • Another example is "numbered"-code, where there are multiple variables like foo0, foo1, foo2. These should be represented by a loop or list instead.
        Point error: having 10 or more instances of repeated code.
        Point error: having 3 or more instances of repeated code.

      3. Magic Numbers
        Your code should not include magic numbers.
        • A magic number is a number used outside of a variable assignment in code that does not have an immediate and clear meaning.
        • In general, every number besides -1, 0, 0.5, 1, 2, and 10 is magic.
        • If you must use a magic number, store the number or an expression using the number in a variable, then use that variable.
        Point error: using any magic numbers.


      4. If/Else Statements
        When reasonable, multiple if statements should be joined into an if-elif-else chain. For example, the following code:
        Point error: not joining-up multiple ifs where appropriate.

      5. if (x < 2): foo() if (x > 10): bar() if (2 <= x <= 10): oh()

        above code should be:

        if (x < 2): foo() elif (x > 10): bar() else: oh()
        Point error: not joining-up multiple ifs where appropriate.

      6. Global Variables
        Global variables can be useful, but they can also be dangerous, and often lead to complicated bugs.
        Point error: using any global variables.