This is an excerpt from my article "Cleaning Up Your Code" on Medium. I'll be publishing each section daily, read ahead on Medium!
Programming is not a math equation. The vast majority of the programs you write will not be simple. They will have to interact with the rest of the program, forming complex relationships along the way, and therefore have to be read by other programmers. Someone with no idea of your contribution should be able to quickly understand what your code does.
Let’s look at an example, which code snippet is easier to grasp?
If you’d like to start using good names throughout your codebase, here are some general rules to follow:
- Expose meaning through names: Similar to the above example, the name of a variable should provide some meaning towards code functionality.
- Use pronounceable names: Software Development involves talking through your code with other developers. It will help a lot if you can actually talk through your code.
- Use searchable names: There will be many times you want to track a variable or function through your codebase. In this case, the variable should be unique enough that it can be searched for with few duplicates.
Thanks for reading! How do you make sure your code is understandable to yourself and colleagues?
Top comments (5)
Also don't forget that in some cases it's perfectly valid to use 'short' names.
It's ok to use i for first iteration and then go to j , k etc for 'sub iterations' since it's a really common practice. Same for 2d/3d coordinates, x y z are perfectly valid, just remember to have it self contained in a decently named function.
I completely agree!
For trivial pieces of code like for loops or even a function that just prints out an array, variable names aren't so important.
Naming conventions become more and more important once you start writing code that can't be trivially understood.
I completely disagree. There is no trivial code. For loops especially need to have clear variable naming. Iterating over i, j, may be a common practice but it does not make it less awful. It has to absolutely clear what data is processed inside a method. Are you sure you even know what to expect if you can't name it?
Of course, for loops by definition point to an 'index' (hence the initial i), and that index is going to be called on a clear named variable.
Yes, "traditional" for-loops work that way... My opinion stems from mainly using languages that have an iterator-based for-loop where the "i" is not the index, but an item.