Good Programming Style

An opinionated set if rules and guidelines
  • 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.
  • While that might make interesting and valuable reading, here I give my own much briefer set of rules of thumb.
  • I will use Bad Code Example 1 and Bad Code Example 2 as we work through the rules and guidelines to try and demonstrate the principles.

Conventions

  • Each language has conventions about how to do certain things.
  • You need to be aware of them and follow them.
  • How do you learn this: Use a code style checker like Rubocop

Ruby naming conventions

  • classes CamelCase
  • variable names snake_case
  • file names snake_case (based on the name of the included class)

File organization


# filename: snake_case name after the class that is defined in the file (if any)
#
# next come the includes (if any)
include "nanoc"
include_relative "nanoc_customized"
#
# next come the single class definiton (one per file)
#
class MyNanocCustomizer
.
end
#
# If the file is meant to be a top level executable then those lines come at the end
#
my_customizer = MyNanocCustomizer.new("Begin")
my_customizer.print_all

Directory Structure

  • There are various conventions, none of them “official”
  • If you are using Rails, it will determine your directory structure

# Rails directory structure
├── app
│   ├── assets
│   ├── channels
│   ├── controllers
│   ├── helpers
│   ├── jobs
│   ├── mailers
│   ├── models
│   └── views
├── config
│   ├── environments
│   ├── initializers
│   └── locales
├── db
│   └── migrate
├── log
├── public
└── test


├── README.md
├── lib
│   ├── app
│   │   └── class_1.rb
│   └── main.rb
└── test
    ├── test_file1.rb
    └── test_helper.rb

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
  • An excellent guideline is to use a name which describes what the thing represents

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.

Well Tested

  • There will always be bugs.
  • Implement automated tests and run them constantly
  • Your work will be judged by its quality
  • If commands fail, give the wrong answers, or look ugly, these are all bugs
  • How do you learn about this? See Code Smells
  • Some people like to check for test coverage

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 sub-step and break them into another method.

Short Classes

  • A corollary 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 design.
  • With the right abstractions and classes and seeing how a class is doing more than one job.
  • You will get get better as you get more practice.

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. *. Indentation should match the nesting structure of your program. *. There should be an empty line before and after each method definition.

Idiomatic Code

  • It is also useful to become familiar with so-called “idiomatic” code.
  • Most languages have more than one way to do something, all valid
  • Programmers experienced in the language always pick one over the other.
  • How do you learn this? By reading other people’s code

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.