Whether you’re planning on working on a project for years, on handing it off to someone else in a month, or writing a full-on external library, there’s one thing you have to keep in mind. Writing clean, reusable code.
Programming can often lead to weird code, and since commenting is annoying, it’s very easy to get lost in your own code a week after writing.
In addition to that, it’s common that a programmer writes pretty much the same code multiple times in different projects. Wouldn’t it be much easier if you could have a personal library of code you use often, copy from that, change a few lines, and save hours in the process?
In today’s blog post, I would like to dive deep into what makes code readable and reusable. One of the main reasons I’m writing this article is that one of my planned projects is a library of often-used code for the Unity game engine. Through research for this blog post, I hope to learn a bit along with you.
With that said, here are my top tips for writing clean and reusable code!
#1. Not Always a Good Idea
Counterintuitively, my first tip on writing reusable code is actually about not writing reusable code.
While it usually is a great idea to write reusable code, that’s not always the case. If you have a very specific piece of code, it’s sometimes not worth the work of making everything reusable. Think about why you want your code to be reusable, when and where is anyone going to reuse it – don’t write reusable code just for the sake of it.
Keep in mind that this does not apply on clean, readable code. Your code should always be easy to read. More on that later.
#2. Functionality First
If you’ve decided you do want to write reusable code, don’t make the mistake of trying to catch every edge case – don’t try to do everything at once.
Chances are, if you’re writing any piece of code, you’re coding it with a very specific problem in mind.
Your code should first focus on solving that one problem. If you try to branch out and solve theoretical future problems, you’ll just write a ton of code you will not be using at the moment. This code will just clutter the whole place up, and will probably be full of bugs.
Rather than trying to solve every future problem, solve the one current problem, and make your code easily extendable.
#3. Keep it Modular
In order to make your code easily extendable, it needs to be modular.
While you could have your code all in one place, it’s generally bad practice to do that. Instead, create functions and classes, that solve only one problem, that do only one specific bit of code, and use them when you need them.
Not only does this help you be more organized, and make your code more readable, it also allows you to very easily add new features (by adding a few new functions), and makes the code easier to bugfix, as you can find the part of code you need very quickly.
#4. Variable & Function Names
Hand in hand with readability go names. This is probably a pretty obvious tip, if you’ve ever worked on a large project, but please name your variables and functions so it’s clear what they are/do.
Naming a variable m for the amount of money a game’s player has is extremely unreadable. You might be able to remember it for a bit, but once you write a few thousands lines of code, or once you take a week-long break from the project, you’ll spend a few minutes trying to find out what m really means. And those minutes add up.
Instead, name your variable something like playerMoney. This way, when you look at a piece of code, you can clearly tell what that variable represents.
The same goes for function names. If a function is supposed to calculate something, for example transfer degrees Celsius to degrees Fahrenheit, name the function something like CelsiusToFahrenheit. Easy to read, clear what it does.
If a function is supposed to do something, name it so it’s clear what it does. For example, VerifyPurchase.
#5. Functions x Classes
Don’t get me wrong, classes are awesome. However, you don’t need a class for everything.
A class, generally speaking, should be a collection of functions that work with a similar thing.
A function should do only one thing. It’s usually also a good idea to have a function either calculate something and return it, or execute some task and return nothing, not both. This will help you avoid hard-to-spot side effects.
#6. Comment Your Code
I know you know you should comment your code. Everyone knows it. But, let’s be honest, almost no one actually does it.
It’s not necessary to comment every single line of code, because your code should be readable even without comments, but it’s still good to explain some of the more complex things.
Comments will come in handy if anyone else looks at your code, or if you look at your code after not seeing it for a week. It will save you precious minutes (that build up over the years), so try to make it a habit to comment.
While some programmers recommend commenting the code as you write it, I find that breaks my immersion and actually slows me down a lot. For that reason, I come back to the code and comment it after I’m finished with my writing sessions.
#7. Document, If You Must
Writing documentation is definitely not a necessity for all code. Hence, this tip applies to only some of your projects – particularly those you will be putting open source, or those you’re planning on returning to after several months.
Documentation is kind of the next step from commenting your code. It explains in detail what everything does and how to use it.
If you’re coding something that will go opensource, or even a library or an API, it’s also good to include a few guides on how to do write common programs. One of the great examples of this is the Discord.js documentation, which is a library that connects NodeJS with Discord, used for coding Discord bots.
My final tip is, iterate. You’re not going to code the most amazing, clean, reusable code on your first try. Try to get it working as it’s supposed to, then come back to it, make it cleaner, make it better. Return to it from time to time, and as you become a more skilled programmer, you’re going to notice pieces of code you could change.
At the end, reusable code isn’t something you should specifically strive to do. It’s mainly something that comes up as a by-product of quality programming.
Reusability can save you a ton of time when working on certain projects, but you don’t have to do everything reusable – just the parts of code that really do repeat a lot.
Keep in mind the best practices of coding, be sure to comment, make your code easily readable by giving variables and functions good names, keep everything as modular as possible, and don’t be afraid to iterate on your work.
If you’ve enjoyed this article, feel free to check out my other ones on this blog, and sign up for my newsletter below. I send out emails pretty often, and I talk about worldbuilding, writing, art, and game development.
You can also join the Eledris Blog Discord server, which is a growing community of worldbuilders and game developers! We’d be happy to welcome you there.