You may already be doing one or more of these tips, so this post might not be for everybody. But if you feel like you could improve your code even by a little bit, read on! Hopefully I can help make your code cleaner and easier to read. Also note, I didn’t title this “Top 10 Ways…” because there might be different steps for different languages, as well as my own error. I’m still learning, and continue every day, these steps are some of what I have learned so far.
Also, this was meant to be a quick read… for a longer version of this article that goes further in depth and contains code examples, check out my other post on this subject, Writing Clean and Readable Code (C# Examples). (Still under development, posting soon!)
Step 1 : Learn the Language
“Think about cookbooks in the original sense. Although great cooks own cookbooks, no one who relies upon cookbooks can be a great cook. A great cook understands ingredients, preparation methods, and cooking methods and knows how they can be combined to make great meals. All a great cook needs to produce a tasty meal is a fully stocked kitchen. In the same way, a great programmer understands language syntax, application frameworks, algorithms, and software engineering principles and knows how they can be combined to make great programs. Give a great programmer a list of specifications , turn him loose with a fully stocked programming environment, and great things will happen.” – Author,V. Anton Spraul (2012) Think Like a Programmer: An Introduction to Creative Problem Solving. Location: No Starch Press
That quote really sums it up. If you are looking to improve your code readability or performance, this is a great place to start. Knowing all the nooks and crannies of a language will allow you to use the language to its full potential. To take this a step further, learn about the different ways to perform a single task, and research the best for each situation. Again, let’s think about this in cooking terms. A knife will still cut, but knowing which knife to use at what time can severely affect the end product.
Step 2 : Refactor Your Method At Least Once, Right Away
We’ve all been there when writing a complex method… You copy and paste code, create variables such as temp1, temp2, etc… and not a single comment is the end result. While the method and logic is still fresh in your mind, take a second before moving on to the unit test, next requirement, etc… and refactor right away. Remember back in highschool or college when you wrote multiple drafts before submitting an original? Yes, the general topic the paper is covering stays the same, but how you explain and structure that paper should increase with quality after each pass. That is how you should approach a complex method in which you just completed.
Step 3 : Look at Every Way To Solve a Problem
For simpler methods, this is not much of an issue. However when approaching larger, more complex methods, or even figuring out the architecture of a future project, one must go through almost every possibility to ensure that you are writing the method or class the best way you can. This step will not only reduce the amount of refactoring you will need to in the future since you have considered a plethora of possibilities, but also reduce the amount of technical debt you create by producing an incorrect or cumbersome solution.
Step 4 : Commenting Your Code
There are two main different comments you should include in your code. The first being in-line comments which serve as a code description for logic or business reason in a method. One way to include them for sure in your end product is to pseudocode your new methods with in-line comments. This will not only increase the readability of the code, but helps you logically set up the method you are about to write.
The second is XML documentation, usually at the top of a class, property, or method. These are important for three different reasons. The first is to describe what a class, property, or method does. This can be quite useful to somebody supporting your code so they don’t have to logically walk through the method to find out what it is doing. The second is to create documentation in intellisense when you are referencing a class or property you made. When created using Microsoft’s recommended tags, you can allow supporting engineers to quickly understand that method you wrote and what it was intended for vs having to navigate to its definition. The final reason is to be able to generate XML from your XML documentation for various uses.
Step 5 : Measure twice, cut once
“The carpenter’s saying, “Measure twice, cut once” is highly relevant to the construction part of software development, which can account for as much as 65 percent of the total project costs.” – Author, Steve McConnell (2004). Code Complete, Second Edition. Location: Microsoft Press
This is in reference to the process before writing the code, the project planning stage. Project planning and gathering accurate business requirements is essential for medium to large projects for clean and easy to follow code. If you try and omit this in your project, you will end up with spaghetti code that will be near impossible to manage later on in the project. A common rule of thumb is specify at least 80% of the business rules up front. If you can stick to this, you can have less surprises, and less spaghetti code.
Step 6 : Generate Programming Standards, and Stick To It!
Another item you and your team can do right off the bat is to generate coding standards for your team to follow. In C#, Microsoft has already started this for you. This will make sure not only you, but your team as well will start outputting cleaner code. Make sure to implement code reviews to find issues before they even hit production environments.
Make sure to post in a general location and to keep updated with new versions of your language’s framework.
Step 7 : Recognize Code Smell
For those of you not familiar with what Code Smell is, it’s basically when code screams to be refactored. This can be when a method is too long, code is duplicated, excessively nested loops, etc… In the beginning of your programming career or learning a new programming language, you might have made a few of these mistakes and didn’t recognize the code smell right away. However, after a few years and beyond these issues should become quite obvious to you. Fix these before you even move on to another method.
Step 8 : Make Methods and Classes as Small as Possible
One way to make your code easy to follow on a project level is the Top Down Design approach. Take your bigger issues and tasks and break down to smaller and smaller components until each method or property covers only a single operation. This will prevent you from creating “god classes” which contains way too much functionality for you or support staff to follow. Creating a very large class or method is common Anti-Pattern.
Step 9 : Using “White Space” To Your Advantage
A pretty obvious step, but one I wanted to make sure I mentioned. The way that we use white space when laying out code changes the way quite a bit of how we perceive a method. Items that are grouped together, for example instantiating local variables, shouldn’t have a line space between the code. However, when you are working with local variables, then a foreach / if then else logic, then you want to make sure you have a blank line in between so your brain can quickly observe the different ‘parts’ of your method. This will help increase productivity of you and the support staff when scanning through a larger class or method.
Step 10 : Explain Your Logic to a Rubber Ducky
The final step is something called Rubber Ducking. Even though usually used when debugging code, I find you can use the same concept when writing new code. When you finish a method, and before you start your first refactoring pass (See Step 2) explain your logic to a rubber duck, or any inanimate object, on your desk. This will have you walk through your own code and catch logic errors you had accidentally scanned over when your first completed the method. This step in conjunction with stepping through executing code greatly decrease the amount of errors, and help you refactor your code to become organized logically.
Again, I hope I helped in some soft of way. If you have other suggestions or comments, please feel free to leave a comment below.