Style Guidelines

Below are some particularly important, recommended style guidelines (and for which you risk losing points if you ignore).

How should I format my code?

• Include a header in every program file. The header should include your name, the file name, and a short description of what the file is about. Something along this line

 /*
  * Draws a cute bear face.
  *
  * file: Bear.kt
  * Project 1: Kotlin & processing basics
  *
  * @author: Jenny Darling
  */

• Indent your code consistently. Use 4 spaces for each indentation level. Do not use hard tabs; different systems and tools display and print tabs differently. You should be able to configure your text editor so that it converts every tab into 4 spaces automatically.

• Do not exceed 75 characters per line. This rule also applies to the readme.txt file. Long lines are hard to read and will annoy your grader. Use line breaks as needed. Use whitespace for readability. Insert blank lines to separate logical sections of your code. Insert a space in front and after an arithmetic operator.

How should I compose a program?

• Use meaningful variables names. Each variable’s purpose should be obvious from its name, if possible. For example, name a variable isOrdered instead of o or ordered. One common exception to this rule is with loop-index variables: they often have short names, such as i or j.

• Use straightforward logic and flow-of-control. For example, you should simplify if (isBlue == true) to if (isBlue).

• Follow directions. For example, if a command-line argument is specified as an integer, read it (and convert its type if necessary) into a variable of type Int; if the assignment says to use a nested loop, then use a nested loop.

• Follow output formats exactly. If the assignments specifies to print Hello, World, don’t print Hello Moon instead. You should also have the specified number of lines of output. (This means that you should remove (or comment out) extraneous debugging print statements before submitting.)

• Avoid magic numbers. A “magic number” is an unnamed numeric constant (other than -1, 0, 1, or 2, used in an obvious manner). Magic numbers make programs hard to debug and maintain. For example, in an assignment on dice rolling, you should define a constant Int variable val NUMBER_OF_DICE = 10 and use that variable name (instead of referring to the number 10 directly).

• Declare variables to minimize scope. For example, don’t declare a variable to be an object property if it is used only as a local variable in one function.

How should I comment my code?

• Include a brief comment above each code “paragraph.” Many experienced programmers write the comments before they write the code. Outlining or mapping out your program before you code is the best way to make sure you fully understand what the program needs to do and to avoid bugs.

• Include a comment describing every function and class (whether public or private).

• Include a comment describing every property (whether public or private).