Be a Better Developer: 2.5 – Being a Janitor - Tips
This blog post is part of a larger series named “Be a Better Developer”. You can check out the intro, “Stop Being a Code Monkey” to get started from the beginning. Each post will have a link to the previous ones and a final summary post will contain links to all entries in the series.
In my last post of this series I talked about keeping your code base clean so that you reduce the amount of technical debt you incur and ensure that your code base doesn’t become the abandoned building with broken windows. In this post I’m going to provide a few ideas on ways to keep the snags out of your codebase and keep the interest you’re paying on that debt low.
Write Good Code
If you write clean code from the start you’ll have less mess to take care of later. This seems pretty obvious, right? It’s like when you are cooking a big meal that requires lots of pots, pans, bowls and utensils. If you do a little cleaning as you go you’ll have a lot less of a mess after dinner. Just write good code and you won’t have a problem.
However, it is a lot easier to say than to do. There seems to be quite the contention around what good code actually is. Since this is my blog and I’m giving my opinion here, good code is “Clean Code”. In my opinion good code is easy to read, easy to maintain and easy to extend. Writing good code means avoiding writing methods that are hundreds of lines long. It means not reusing variables within a method. It means not having massive nested IF statements. If you haven’t read Clean Code by Robert Martin I think it is a good place to start. Follow it up with *Working Effectively with Legacy Code *by Michael Feathers.
****Practice Low Impact Coding ****
When I was a Boy Scout out backpacking we tried to practice “low impact camping”, which meant trying to impact the environment as little as possible. We tried to utilize existing fire rings, didn’t dig trenches, packed trash out (even if it wasn’t ours), etc. When you’re coding you can actually do some of the same types of things. For example, look for ways to make changes to the code base to implement your feature so that it has the least impact to the existing codebase. This will likely lead you down the path of having better separation of concerns. It also moves you toward the Open Close Principle, giving you the ability to extend and add new features without affecting much of the code you already have in place. In those places where you are having to crack open the existing code to provide the new functionality take a second to think about what this impact is going to do.
This is not to say that you should implement everything you do using multiple abstractions and Inversion of Control Containers, etc.; however, I do believe you should take a few moments of time as you implement each feature and think, “If I had to come in and change this to do something else, how hard will that be?”. If you practice writing “Clean Code” then it should be easier to come back later and add those mechanisms in if you need them. Don’t let this type of internal questioning lead you down the path of over engineering your solutions though. As with all things in our industry, there are trade offs with every decision you make. If you think some of your approaches might be over the top (or even if you don’t) ask a fellow developer to look at them and get their opinion.
Clean Up After Yourself….and others
Also back when I was a Boy Scout we had a saying: “Always leave a campsite better than when you found it”. This meant that when we left a campsite we tried to make sure there was firewood for the next person (or at least enough to get a fire going), trash was picked up, etc. When you are coding you can definitely clean up after yourself and others.
Remove dead code – If the function is no longer called then get rid of it. If the function is being phased out and it is public then make sure to deprecate it in some manner (in .NET we have the obsolete attribute). This is especially true if you come across a method that is completely commented out. Just get it out of the code completely. Source Control will take care of making sure you can put it back later if you need to. At best commented functions are distracting and worst they are misleading (sorry, this is one of my pet peeves). Also, a lot of code compare tools won’t show syntax highlighting, meaning it’s very easy to look over the fact that some code is commented out.
If you are removing a function call from something you are working on, take the time to see if that function is called from anywhere else. You may have just removed the need for an entire sub-system! Reducing your code base while meeting your requirements and implementing new features should be considered a win. It is almost always a good thing to reduce your code base complexity whenever possible.
*Translate comments into descriptive code *– I’m not going to get into the religious war on if you should write comments or not, but I will say that descriptive code is much better maintained than any comment will ever be. Your mileage may vary, but I have found for me that using descriptive method names and variables provide a much nicer experience when coding than comments ever did.
Most of my code doesn’t have comments in it. If I’m writing a framework component then the public classes and methods likely have the XML Comments on them to allow for intellisense and API documentation; however, the private methods are mostly devoid of comments. I attempt to make the code as readable and understandable as possible.
**Periodically Give the Code a Good Once Over **
There is something to be said for the idea of doing a little daily cleaning so that you don’t end up with a much harder to clean mess later. Think about your kitchen counter. If you spend thirty seconds after you finish washing the dishes to wipe down the counter and get any food bits and grease up, doesn’t that keep you from having break out the HazMat suit and liquid fire to clean the counter if you let it go for a year? Same thing with a code base. If you periodically go through the code and identify places that could use some refactoring or cleaning, you may save yourself a lot of pain later. I’m not saying spend hours doing this, or even that you have to tackle the issues you find immediately. Keep a list of problem areas you find and hit them when you have down time or the next time someone is in that part of the code, or just put them on the backlog of things to tackle when it makes sense to do so (make sure to include the business value of having clean code in your backlog item description!).
Conclusion
Most developers work in code at least some every day (if they don’t they’d be called managers or architects) and it is a much nicer experience when you work with good, clean code. Learn to clean up after yourself (and others), learn to keep the code base uncluttered and you (and the other developers you work with) will be much happier for it.
Previous Posts in this series: