Saturday, September 20, 2008

Coding Style

While at Google at got exerience with code reviews. Code readability and style is taken very seriously there and can drag out code reviews. So, I looked back at comments I received in our web integrated revision control system to see what my common issues where. I found a lot of stuff about style one would usually not notice.

  • Comment Grammar. They do check for spelling and Grammar in your comments. It gets kind of annoying to edit your sentences when you have to manually break at 80 cols and enter a new comment symbol. It would be cool if there was an IDE that would pop up a text box and let you type with a spell checker and a grammer checker. Then it would insert it into the code for you.
  • 80 characters line width. Seems like those 82's always sneak in. Check your code with a linter to find this kind of stuff!
  • Put a good description of the input and output of a program at the top. In a doc comment if your using Python
  • Document why your using < vs <=. This helps avoid of by one errors.
  • Variable names: The have to be descriptive, but not too long. Its is a definite trade off. I guess there is a feng shui to this one.
  • Capitilization style: the is usually a convention for capitilzation for variables, global constants, class names and function names. Some lint tools do this.
  • White space rules: for indentation and line continuation. (lintable)
  • Whitespace after , or binary operators. There is also not supposed to be whitespace at the end of a line. (lintable)
  • Don't hard code in any numbers, filenames, or many strings. They should be global constants.
  • Put the units in a variable name if it is a quanitity with a unit such as seconds
  • Use libraries whenever possible. This is why it is important to know what all the libraries do.
  • Avoid deprecated code.
  • Avoid redundant functions calls. For example, using flush() before close() if close does flush automatically.
  • Comment almost every line. There is probably some good ratio of comment lines to code lines if you where to compile some stats. Don't explain the language in the comments explain the program. To do otherwise would violate style rules as well.

No comments: