Good Programming Style

Background

Like good writing style, good programming style is important, subtle, nuanced, and often a matter of opinion. Yet over the years we have learned many fundamental guidelines and rules which most everyone agrees makes for good style.

Actually whole books and elaborate handbooks have been written about this, for example: Google Java Style Guide, Java Ranch Programming Style Guide, a really old but good book by the co-inventor of C: Elements of Programming Stle. And lots of others.

While that might make interesting and valuable reading, here I give my own much briefer set of rules of thumb.

Rules of Thumb

  • Short Methods: Try hard not to exceed about 15 lines in a method. If it feels like you can’t make it shorter, look for a set of statements in the method which do some substep and break them into another method.

  • Short Classes: A correlary of the previous is to try and keep your classes to 100 lines or less. This one might be more difficult to follow because often its a matter of designing the right abstractions and classes or seeing how a class is doing more than one job. You will get get better as you get more practice.

  • DRY: DRY is a software engineering slogan meaning “Do Not Repeat Yourself”. It means, in the simplest sense, no textual duplication of lines of code. If you find yourself cutting and pasting some lines of code from one place to another, your code is not DRY. This is an opportunity to create a new method, with a good name, and call it from both the places. In a more advanced sense it means that you should not duplicate concepts or knowledge.

  • Intention Revealing Names: You have to make up names for variables, methods, classes, packages, parameters, files and more. Whether the name you pick is “good” is kind of a matter of taste, but an excellent guideline is to us a name which describes what the thing represents.

    For example, if I have a method to find the largest integer in an array, I might call it returnLargestInt(). If I want to write a class which represents a planet in my game, I might call it Planet. And if a class returns a boolean (true or false) in Java we often write it like this isPlanet(), that is starting with the word “if”.

  • Whitespace: Most programming languages (python is a notable exception) totally ignore whitespace. You can put in extra spaces, tabs and newlines just about anywhere without changing what the program does. But you can hugely change how readable it is. Here are some guidelines:

    • Indentation should match the nesting structure of your program. In Java this might translate into adding 3 spaces to the beginning of a line after a {open curly brace and taking away 3 in the lines after a closing curly brace}.
    • There should be an empty line before and after each method definition.
  • Commenting: Don’t comment too much or too little. Ok that’s not so helpful. But really you should add comments only when the code doesn’t speak for itself. If the method is called “returnLargestInt” then don’t add a comment that says, this method returns the largest integer. But if it uses an interesting algorithm to do this, or it has error cases or other unusual behavior, that that might deserve an comment.

  • Java conventions: In Java the convention is that class names are WrittenLikeThis, which we call upper camelcase. Method names are writtenLikeThis, which we call lower camel case.