Software is constantly changing. Code that may be perfect now will have to be edited in the future. While your team will probably be tasked with making the change, you may not be the one doing the work. You may be on a different assignment. Maybe you are no longer on the team, having been promoted to VP of Perfect Coding. Maybe you left the company to finally follow your passion for competitive ice sculpting. Or, worst-case scenario, you were assigned the fix but you forget what you meant months ago when you wrote the code. Code that is easily read is easily understood, making it easier to fix.
Broken but readable code can be made functional. Unreadable code that works, for now, will stop working eventually, perhaps because a bug was found or the requirements changed. Broken, unreadable code is worthless. Obfuscated code is often thrown out and recreated from scratch because the time and effort to do so is less than decrypting and editing the code in its current state.
As a developer, it’s important to make readability a priority. Follow simple practices and your code will be readable and much easier to work with. Not all of these tips apply to all languages since different languages have different rules and criteria. So, discuss this advice with your teammates and see what you can use for your projects.
Follow a reasonable naming convention
For one, follow a reasonable naming convention. Create identifiers that convey structure, type, and use of the item being identified. Having guidelines that are followed by the other developers in your team will greatly reduce the amount of time anyone has to take to decode your code.
Common conventions include:
- The content of an identifier should relate to the data being accessed or the task being executed. Have a special function to delete all outgoing students? Perhaps call it deleteAllOutgoingStudents(). Yes, that’s a relatively long name to type, but think of the time you’ll save in the future when you read that name and know exactly what that function does.
- Function names begin with verbs. Class names are singular nouns.
- Function names are camel-cased. Class names are capitalized. Constants are in all caps. Variables are all lower case.
- Boolean data type values begin with “is” (e.g. isloggedin as a variable name)
- In general, avoid single-letter names. While a loop control or index variable “i” is often an exception, I’d suggest avoiding this, too. When someone unfamiliar with the code sees “i”, they will have to check to see how it’s used to figure out what it is. A variable named “index” requires significantly less research to understand what it contains.
Use proper indenting
Another way to improve readability is to use proper indenting when coding in a language that ignores whitespace. Lines of code that are indented properly can make it very easy to see what lines will execute together and what lines are dependent on a function call or the test condition evaluation in order to execute. Being able to quickly ascertain which statements are linked together can make it very easy to trace the path of execution without having to actually execute the code.
There are common disagreements among programmers as to whether spaces or tabs should be used to create the indenting on each line. Different editors may render the two options differently. Whichever you use, agree as a group, and set a standard. You’d be surprised how much confusion this issue can cause when the two options get mixed. Depending on the editor you use, you may have access to “auto-formatting” or “pretty printing” features that will read your code and correct indentation along with other matters such as aligning curly braces. So, following this piece of advice may be as simple as a button click, in the end.
Consider line simplification
Consider simplifying your lines of code. In many languages, one line of code can contain steps frequently separated into multiple lines (i.e. function calls, variable assignments, test conditions, etc.). While one intricate line of code may work perfectly well, two problems often arise. First, debugging a line like that may be impossible in some editors. Second, understanding the process may take a significant amount of time.
In breaking the steps into multiple lines of code, a complicated process will become easier to read and understand. It would be as if it were being described by short and clear sentences instead of one that is long and intricate. Keep in mind that many compilers will optimize the code you write before execution. The executable code will usually be based on the individual steps in the process, regardless of their presentation on one line or multiple lines in the original file. So, since it makes no difference to the computer in the end, save yourself some time in reading and working with the code and go with simpler, multiple lines.
Augment understanding with comments
Commenting can be a useful tool but is often the first, only, and most overused tool among novice programmers. Properly indented lines of code of reasonable length with readable identifiers will often become self-explanatory to the trained programmer. Comments can then be used to augment understanding and explain what is not evident in the code. Well-written code details the steps in a process, but a simplified explanation or quick statement of the reason or purpose may help in working with it. Use comments to convey the simplified explanation and reasoning.
While writing readable code won’t guarantee that your coworkers will think fondly of you, but it may help you avoid hours explaining why you used an unnecessary recursive algorithm in code you wrote months ago.
