Simple Things That Makes Your Code Look Better
Chapter 1 - Naming
Containers — constants and variables
Containers — when I talk about containers in Swift I mean anything that can store some value — variables (var) and constants (let). So imagine you need to keep some number in your program, first question you should ask yourself — How to call a container to store this thing?
The basic rule to give variables good names — call them nouns, the name should describe what’s in the container in the context of scope it’s defined without overlapping with other values.
Prefix/SuffixContext — it’s cool when your code has 3 labels and you know them as your fingers, but what if it’s more than 10 labels and you worked on this code 2 weeks ago? The trick here is simply adding the suffix of “what element is” when giving them names for ex. Array, Label, Button and so on, and when you will need a particular label you can just type “label” and Xcode comes up with a list of elements that contain “label” in their name.
is (prefix) — for Bool
Count (suffix) — for numeric values
Nesting is also a good way to add prefixes eq
box.size.width = Constants.itemSideLength
Functions
Call them as verbs. Function names should reflect actions that are performing like fetch, reduce, check, filter and so on. At some point of my career, I understood that the best approach for naming anything in code — this is decomposition and especially top-down design that I’ve learned from
Prof. Mehran Sahami on CS106A course. The trick here is when you trying to reach something in your code (for example some state that requires to check variables A, B and C) you immediately write this state into your if statement eq if userSavedAllAssets {…} providing it a reasonable name without actually having it in code and then when the condition looks clear, you define the userSavedAllAssets function or variable and start working on it.
Print labels
Let’s say you run a console program that gives you a sum of two numbers and it looks like this:
3
4
7
Awesome ha? We could dramatically improve it by adding some labels so it can look even better:
Enter first number: 3
Enter second number: 4
The sum of 3 and 4 equals 7
Much more user-friendly!
Just imagine that your code contains thousands of values that could be printed as those three mentioned above.
Once I spent 2–3 hours watching unlabeled numbers on debug console and wondering WHY THEY CHANGED independently of my actions. Since I recognized that numbers source wasn’t expected I started to add labels to each of my print statements to get a better understanding of what’s going on under the hood of my program.
It helped not only with an understanding of “what is this output about”, but also with simple searching them inside code and faster navigation.
Worst naming case
What could be “better” than this?
var a = 5
Masking something uncommon in well-known containers such as pi that all of us know as 3.14159… number, so if we imagine that we looking into an expression where pi operates with other operands, well-known members such as pi will be last on your inspection list. Use constants to avoid those scenarios. If pi is a variable that could be a problem in the future when it’s value changes but even if we define it as a constant we could get in trouble on assigning a value to it:
let pi = 3.14157
It's better to use Swift predefined constants such as Double.pi or CGFloat.pi
In case with var a I'm don't know what is inside and this fact requires me to dive into it and find out its purpose and possible changes, but in the case of pi I am sure that it contains the right number so as consequence I should spend much more time to find out what part of code hiding this problem is.
Be sure that your name describes the content of functions, enums, containers and other namable parts of code as more as possible.
https://swift.org/documentation/api-design-guidelines/#naming
