Comments, Naming, and Readability

A lot of code is difficult to read, and a lot of programmers are doing their best to keep it that way. To me, this seems like a move that Wally (from Dilbert) would use to ensure he doesn’t get fired.

But in reality, someone WILL look at your code. It might be to replace you, but more than likely it will be to help you debug something. Not to mention, that someone might be the future you. So here are some guidelines I use for keeping my code readable.

Stick to One Formatting Style

This is probably the easiest to get used to. Pick one way of formatting your code, and keep it that way. If you like braces after your if to be on the same line, keep all of them on the same line. Indent where needed and keep it a uniform size. Switching between formatting is something that will be jarring to anyone reading your code.

If you are in a team, decide on a shared format and have everyone stick to it.

Use Names That Make Sense

Name your code after what is does. Names should describe who, what, where, or how something is being done. Using long names is perfectly fine. Many programmers enjoy using short names and abbreviations (think AOL-speak). You might understand it, but no one else knows that klalhmn = false is really standing in for killAllHumans = false. Say what you mean, and mean what you say. Your monitor probably supports more than 80 characters per line, so why shouldn’t you?

Comments in Code

Comments are great, regardless of how bad they are. But writing comments is boring. If you are following the above advice about naming, you may not even need them. So why try to write comments, and what should you write? Write the WHY in the comments. Lets take a look at how comments can help:

let klalhmn = false    // Set Kill All Humans to false

In this case, the comments are useful for explaining some of the code. But this explanation might not be good enough. In fact, you’re just explaining your unreadable code to start with. Wouldn’t it be better to have understandable code?

let killAllHumans = false    // This code controls nukes so a safeguard is needed

This is much better. We already know what the variable controls and what the value is, so we just add our reason why. I admit that this example is a little too simple, but imagine that you spent an entire day debugging some code that should be simple in theory, but is hitting an edge case. Next time you look at the code, you may not recognize the edge case and remove your glorious fix. Put a comment on anything that isn’t intuitive or expressive by itself.

Comments in Headers

How many times have you been mistaken about a property or public method? Imagine properties like tintColor or completionBlock. What is tinted? What thread is the completion block run on? Other programmers should not have to hunt through your code to find the answers to these questions. State anything that might be important to note in your headers.

Hard-Coded Values

Lets say we have a UITableView with a height of 20.0. How many would use this code?

func tableView(UITableView, heightForRowAt: IndexPath) {
    return 20.0
}

Now, lets say I want to center a label in my cell:

cell.label.center = CGPoint(x: cell.center.x, y: 20.0 / 2.0)

So, where does 20.0 come from? Why is it being cut in half? Simply looking at this code makes it hard to understand some of the numbers. Now, what if the height were to change to 40.0? The label would look awfully weird, and we would need to hunt for every 20.0, check to see if it is related to the cell (somehow), and replace it if needed. Wouldn’t it be better to use a let (or OBJC #define or const)? Not only would that help in the event that the value changes, but by providing a name, we also assure that we know what that value relates to.

In short, your code should read like a book. If there is anything that is not easily understandable, then you are wasting some future programmer time.