There is a saying that goes:
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live”.
Sometimes while coding, during a burst of inspiration, you may forget that in the future you, or another developer, will come back to that code to make a change. It can only help if you consider your future self or another developer who will one day use your code. You can help make their life a little bit easier by following some good practices when documenting or writing code.
Add useful comments
It’s true that the most common scenario is racing the clock during a project and adding comments might seem like a waste of precious time.
Actually, when you go back to your code 6 months later to make a change, the code will probably be unfamiliar.
Remember to add useful comments. A useful comment is not a narration of your code. For example, before making a comparison adding a comment like “making a comparison” is unnecessary.
Comments like that you make your code “noisy”. Notate what your code does instead of how it does it.
There are a lot of ways to make code more organized and easier to read. For instance, you can be consistent with the way you use curly braces (in a new line or in the same line).
Use indentation consistently. Not only does it make code more readable but it also helps you to identify some missing tags when you make a massive change.
You can also consider separating the code into blocks. For example, you could leave some space between methods in a class or between groups of lines of code that make specific tasks. Maybe even throw some comments in the middle.
Use descriptive names
Make sure that the name you use for variables, methods, classes, etc. are in some way descriptive and help you to identify the purpose of that variable or method.
For example, names like:
update_user are names that when you read them you get an idea of the purpose of that variable or method. Avoid being too descriptive; don’t use names that are too long. An example of a bad name for variable would be:
We can all agree that’s a little too much. For consistency’s sake you and your team should consider adopting a standard like CamelCase or use underscores.
Read some else’s code
In your spare time try to read code written by someone you admire; that could be a developer you follow on the web or a co-worker you look up to. You can learn a lot!
Take a moment to double check
Whenever you have the chance, code a method or a block of lines and take a minute to check if you can make your code simpler.
You might consider using another function, or another conditional structure, or some other change you can make that will make things easier when you have to make a change in the future. Whenever you have the opportunity to improve or make some code easier to maintain, go for it!