Style Guide

Engineering software in a professional environment requires code that looks consistent, regardless of its original author. It is very, very rare that a program component written by one person is never read, understood, or modified by someone else in the organization/project. To be consistent, engineers follow some basic guidelines about how they format their code. These guidelines are documented in a style guide.

Think of this akin to the grammar of a language. When grammar is correct, text is easy to read. If done bad its real hard even if words themselves is ok.

Google articulates the point like this:

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it.

A real-world example is Google’s Python Style Guide.^[1] In fact, Python itself has a style guide.

In this class, we will obviously be less rigid about style, but we will have standards.

Comments

Engineers should always try to make their code explain itself. This means that someone other than the author should be able to read the code and immediately understand what it’s doing.

In some cases that is very hard to achieve. When code isn’t self-explaining, comments are more valuable than the code itself!

If your code is not self-explaining, comments are necessary. But, if your code is self-explaining, comments are just distracting. You should always strive for self-explaining code, but, when that’s not possible, you should use comments.

For example, consider the following statements:

dv=f/m

acceleration = force / mass

max_user_budget = 500.0  # Users have a maximum budget of $500

bounded_value = min(1.0, max(0.0, value))  # Bound value between 0 and 1.

Statements 1 and 2 are the same, but are very different in how readable they are.

Statements 3 and 4 illustrate cases where a comment is necessary (4) vs. unnecessary (3).

Required comments

Every program (.py) file that you write should have at least the following at the top of it:

Your name
Course name
Project name
Honor code pledge
Description of what the program does

For example:

# Author: Marion Lang
# Class: COMP141'f19
# Project: Twimblr
# Pledge: I have neither given nor received unauthorized aid on this program. 
# Description: Twimblr is an entirely new and novel and not at all derivative
#   microblogging system where a user may follow a collection of other users 
#   and see updates from those they follow in their 'console.'

Comments on functions

Every function should have a comment that documents its parameters and return values. The comment must include the following:

A description of what the function does.
A description of each of the function’s parameters.
A description of the return value, if the function returns a value.

Example:

# Compute whether a user is popular.
# Args:
#   followers: the number of followers the user has.
# Returns:
#   True if the user is popular, otherwise False.
def is_popular(followers):
  ...

Naming things

Variable names should be descriptive. If the name has multiple words, separate them with an _. Variables and functions should only contain lower case letters, unless the name contains an acronym or initialism

num_followers = 1000 # Good.
recentPostCount = 10 # Bad.
is_HTML_post = True # OK.

Note that other programming languages and style guides use a different format.

Whitespace and other things

Always separate operators from operands by a single space. Use parenthesis when necessary or when they help one understand the computation.

1*2+3 # Bad -- no spaces.
(1 + 2) + 3 # Bad -- unnecessary parens.

1 * 2 + 3 # Good -- spaces, no unnecessary parens.
(1 * 2) + 3 # Better -- parens help to understand what happens first.

Readability at Google

At Google you are required to know the style guide for the language you write code in. If you are an expert in a certain language and have committed the style guide to memory, you are given readability in that language. Someone who writes a lot of Python will get Python readability.

When you try to check code into the Google codebase, your code needs to be reviewed by at least one other person. In addition, you are required to get approval of your code by someone who has readability in the language of your code.

Basically, if you don’t follow the style guide, your code doesn’t get to be checked in, no matter how brilliant it is.