General Style Guidelines

in CS 102 on Programming Basics

Guidelines to writing “pretty” code, applicable to most programming languages

This is an attempt to describe how code should be formatted. It’s a combination of my notes when I was learning programming and what I’ve learned from my students. This reference sheet will get better over time as I add to it and organize it further.

Indentation

Always tabs, or always four spaces (Silicon Valley - S3 E6). Choose one. Stick with it.

Spacing

  • Always a space after if and the bracket. Use if (blah) {, not if(blah){.
  • No single line if blocks
      if (blah) {/* do something */}
  else {/* do something else */}

    Instead use

      if (blah) {
      /* do something */
  } else {
      /* do something else */
  }
  • No spaces at inside ends of parens
      if ( blah ) // bad
  if (blah ) 	// badder
  if (blah) 	// good
  • If multiple conditions, space out each operator and symbol
      if ((x&&y)||(z%10==0)) 			// bad
  if ((x &&y) ||(z %10 ==0) )		// badder
  if ((x && y) || (z % 10 == 0)) 	// good
  • An empty block should be { } not {} with an explanation as a comment
      if (emptyBlock) {
      // a useful comment here about why this case is skipped
  }
  • Use spaces after a commas: aFunction(apple, banana, celery) not aFunction(apple,banana,celery)
  • Use spaces before and after use of +
      string good = "this is an " + "excessive use " + "of quotes to demonstrate concatenation.";
  string bad = "this is the "+adjective+" wrong way "+exclamation+" and is difficult to read";
  • Spaces before and after operators in almost all cases: for (int i = 0; i < 10; i++) {
  • Use parentheses to clarify the order of operations: int a = 13 + (b * 12) + (c * 5);

Brace Yourself

  • Always use braces:
      if (i = 0){ //good
      i = 5;
  }

    Never choose to omit the braces:

      if (i = 0) //bad
      i = 5;
  • Starting brace goes on the same line, end brace goes on its own. For example, an else statement should look like } else {

Blank Lines

  • Use two blank lines between function blocks
  • One blank line after package declaration
  • One blank line between imports and class definition
  • One blank line between variables/imports that can be further categories (e.g., constants, math-related packages)
  • No blank line after the function definition or before the closing brace

Other Stuff

  • Use if (blah == null) instead of if (null == blah)
  • Use the ternary operator (?) if it most clearly saves multiple lines of code, i.e., return (something == null) ? 0 : something

Functions

  • If you need to change the number of parameters, add to the end.
  • Don’t change the order of parameters when the function is already declared, defined, and called.
  • Don’t have alternate forms of the same functions with the same types of parameters (not overloading, but redoing).

Comments

  • Always one space after the // in single line comments
  • Use /* */ before a function to describe its purpose, even if the description fits on a single line
/* does something */
int aFunction () {
	int a = 0; // placeholder for user input
}

New Lines

  • Keep code under 80 columns. Break up statements if you must.
  • Avoid excessive chaining, where dots are placed at the end/beginning of multi-line indented poetry

Layout

  • Don’t stack declarations/definitions
      public static final int STATUS_EMPTY = 100, STATUS_COMPILER_ERR = 200, STATUS_WARNING = 300, STATUS_INFO = 400, STATUS_ERR = 500;

    Because perhaps someday, you’re going to need to change something and won’t easily find it. Use:

          static final int STATUS_EMPTY = 100;
      static final int STATUS_COMPILER_ERR = 200;
      //...etc
  • You don’t have to be cute and tab-align for symmetry. It’s subjective, but if it helps with readability by all means be cute.
      string grocery = "Buy " 	+ num1 + 	adjective 	+ " apples 		\n" +
                   "Taste " 	+ num2 + 	verb 		+ " bagels 		\n" + 
                   "Find " 	+ num3 + 	adverb 		+ " jellybeans"		;

Names

  • Everything (e.g., functions, variables, classes) should have a purposeful name that relates to what it does
  • Names should not be a smash of more than 2 words. getName() is good, but getNameFromTheUserWhoExistsOnTheOtherSideOfTheConsole() is silly.
  • Primitive variables should be a lowercase single word (e.g., num)
  • Objects and classes should be a single word, first letter capitalized (e.g., Student)
  • Functions can be either one or a smash of two words, first word lowercase, second word capitalized (e.g., getValue())
  • Constants should be in all uppercase letters (e.g.,INT_MAX)

Copyrights & Attribution

  • Your full name, the date, version no., title, and the purpose of your program should be in a multiline comment at line 1 in the format below.
      /*
      Rebecca Ramnauth
      Advanced Calculator Project v.6.0.1
      28 February 2019
		
      A calculator with an digital interface for the console,
      capable to performing + - / * and % operations.
  */
  • If you need to cite a source/reference, include the link and describe what you used the source for in a multiline comment.
      /* 	
      font from: fontawesome.com 
      color from: colorpicker.com
      equation adapted from: https://github.com/rramnauth2220 | @rramnauth2220
  */
  • When possible, cite on a per function basis.
  • If using external APIs or other resources that influence the program generally, include a README.txt file in the first level of your source repository

Philosophical

  • Multiple classes in one file is okay, but don’t reference the inner classes from the same file
  • Order if-else-if blocks. Where possible, make the default case the first part of the if block

© 2020. Some rights reserved.