Alright, on to our first post in this (hopefully) long series. And before you think “Oh great, the first post and already a lecture”, well yes, kind of. But stick with me, I’ll try to make it quick so we can move on to more fun stuff.
What are naming conventions, and why should I even bother?
I’m going to answer the second question first, so we can move on.
Let’s say you’re working within a group of three people, so you and two other team members. You’re new to the group and still need to learn how things work at the company. One of your coworkers doesn’t care at all about naming conventions and abbreviates everything, so all his properties are called
numOfUsrs. The other one tries too hard and almost ends up writing a book with every property name like so
thisPropertyIsCalledNumberOfUsersAndStoresAnArrayOfUsers. Now imagine that this is the case in a very large project with hundreds of files and thousands of lines of code. Pretty frustrating, isn’t it?
This is where naming conventions come into place. Instead of “doing whatever you want” Apple wants us to use clear names throughout our code, whether it’s in a Playground or a huge Xcode project. But what are clear names and how do I find out if the name I’ve given to a property/dictionary key/type qualifies as a good name?
Well, from here on we need to distinguish some of the parts of your code.
A good name for a Boolean value can be read as part of a question.
isAuthenticated are just examples but they immediately make clear that if you add this to an if-statement the return value will only ever be
if user.isAuthenticated almost reads like something you would ask another person whereas
if user.authenticated doesn’t as much.
Integer, Double and Float values are best represented by using a name that implies some sort of numerical meaning.
userHeight are names that imply a numerical value being returned.
users rather sounds like an array of
It’s nothing wrong about pre- or suffixing the name of the variable with
String if there is no other way to describe the value.
urlString can be used to clarify that the value returned is a
String rather than an actual
For everything else make sure that the name represents a textual representation of the return value.
messageText is as good as
message implies a custom object rather than a
The same rules described above apply to function declarations. Does your function return a
Bool, give it a name that implies so.
hasLoggedInBefore can be just as good a name for a variable as for a function. The only difference between functions and variables is that functions execute a certain kind of task, so make sure that the name reflects that.
users() could also be named
fetchUsers() if you get the users from an external API for example.
Classes, structs, enums and protocols - also referred to as types - should read as nouns and aim to represent something found in real life. So, a type modeling a game mode could be called
EasyMode, a superclass for all kinds of vehicles
The only real exception to this are protocols. As per the definition by Apple’s API design guidelines protocols that describe what something is should read as nouns (e.g.
Collection) and protocols that describe a capability should be named using the suffixes
Comments don’t actually belong to this topic, but I don’t want to write another blog post about them, so I just include them here. Comments are the best opportunity for you to explain what a particular piece of code does. And while I myself am not a big fan of writing long comments, you don’t actually have to. Just write one or two sentences about what a function does, what kind of value a variable returns or what kind of rules a protocol defines.
And while something like
//MARK: - Properties qualifies as a comment, this is actually only a marker so Xcode can show you certain areas of your code in the jump bar. So, please for your future self and coworkers, take the time to write a meaningful comment.
Well, here it is. My very first blog post in a hopefully long series. As a final note I would like to quote something that I’ve found on Twitter and which surprisingly came up just before I finished this post:
Any fool can write code that a computer can understand. Good programmers can write code that humans understand — Martin Fowler
You might have just begun the journey of learning to program, but nevertheless it is important to remember for the future that if you want to become a good programmer, write code that reads as a good book and doesn’t cost you countless hours of debugging.