How To Name Things In Your Code So That You’ll Be Able To Jump Back In Months Later As If You Had Just Written It
My thinking on this has definitely changed over the years. I’ve made a lot of mistakes here. Not the type of mistakes where something is wrong without question. The type of mistakes where as my experience grows and I look back and remember code that I’ve written, I would have done things differently.
But here’s the thing with this type of mistake. You can’t let it stop you. Why? Because I know for certain that some of the ways I do things today will continue to change. Five years from now, I’ll probably wish I had done things differently. There’s no way to know at this point in time which things I’ll change my mind about later. I just know it will happen. We all need to grow and continue to learn new skills.
I remember once when I was first starting to learn programming and I named a variable lagi. It means “again” in the Malay language. I used it to keep track of whether or not to continue a loop. It seemed perfectly reasonable at the time. I stick to English words nowadays. Not because I wouldn’t understand my code but because I want you to be able to understand my code. Or another programmer. It was over twenty years ago and was just one variable in a tiny program that doesn’t exist anymore. But it’s strange how I remember it.
Good code should almost document itself. You should be able to read it and understand it. And other programmers should be able to read and understand your code too. If you name your variables x, y, and z, then they’d better represent the X, Y, and Z axis. Anything else is just too confusing. And naming a method “processWork” is just as useless.
Your names should be self explanatory. If you find yourself explaining the meaning of your names in a comment, then it’s a strong sign that you’re using bad names.
A variable name should describe what it is. A method name should describe what it does. A class name should describe its responsibility. And don’t forget file names. They’re just as important to help keep your code organized as the other names are to keeping it understandable.
Be consistent in your naming and how you capitalize parts of the name. You’ll learn about casing in this class.
- Camel casing.
- Pascal casing.
- Should you use Hungarian notation?
- How should you name member variables vs. local variables?
- A method should do something so make sure to use a verb.
- Avoid doing multiple tasks in a method. One clue to when a method is trying to do too much is when you want to put the word “and” in the method name.
- Should a class name follow advice for a variable, a function, or something else?
- And what about structs? Aren’t they almost the same thing as classes?
You’ll also get advice on how to name other things:
- How to name an enum type. This includes the enum values too.
- How to name a const type. This can help make your code easier to understand and modify by naming a concept in one place.
- How to name a namespace. What makes a good namespace and should you have multiple namespaces nested inside one another?
- How to name your files and the directories they live in.