Tips on Writing Readable Code

Code readability may be defined as the convenience with which the source code is understood and modified. Code readability is of vital importance when maintaining larger legacy codebase and working in teams. If the code is easy to read, it would be easy to debug, refactor, enhance and maintain, thereby reducing the lifecycle cost of software product. As readability directly impacts software quality, researchers have proposed adding a separate phase during development focused on improving code readability. Although, code readability is subjective to human judgement, static analysis tools can provide a fair estimate on various factors impacting readability such as indenting, naming and commenting. As a programmer, follow the tips provided below to create self-documenting software program, which can be understood conveniently by other programmers during it's lifetime.

• Use Descriptive Naming for Identifiers. Code identifiers such as class, method or variable names should perfectly describe their purpose. A few examples of meaningful identifier names are:
• Method Names: createNewStudent( ), setStudentName (String studentName)
• Variable Names: employeeAge, itemId, testResult, arraySize, isEmpty 

• Use Consistent Naming for Identifiers. Use consistent naming convention for various identifiers in source code. For collaborative working, follow standard conventions agreed within team members. Popular programming languages also suggest a standard code styling guide for programmers, typically a part of static analysis checks in corresponding IDEs. The temporary names, typically used as loop counters, should be consistent in complete code. Typical naming convention rules are:  
• Class names should use camel case e.g. GroceryList
• Variable / object names should use lower case followed by camel case e.g. studentAge
• Method names should use lower case verb followed by camel case e.g. setPassword( )
• Package names should use lower case e.g. com.malikumer.bughunters 
• Constants should use upper case with _ to separate words e.g. MAX_VALUE = 100

“There are only two hard things in computer science: 
cache invalidation and naming things.” 
Phil Karlton

• Indent the Code Properly. Use proper and consistent indentation in source code to make underlying logic and structure more obvious and understandable to readers. As a general rule, code between curly brackets needs to be indented using 'TAB' key. Separate different blocks of code using spaces and comments. 

Example of Un-indented vs Indented Code

• Simplify the Code.  Simplify the code, making it understandable and clear without the need of comments, even if it takes more lines of code. Use abstraction to eliminate repeated code and simplify conditional statements. Reduce the level of nesting and the length of single code statement, if it helps to improve code readability. 



Example of Repeated vs Non-Repeated Code
 

“Code never lies; comments sometimes do.” 

Ron Jeffries

• Comment the Code. Commenting makes understanding the code and maintaining it much easier. Code must be commented so that it explains the purpose of code as well as the algorithms used to accomplish the purpose. To comment the code, a comment block may be placed on top of a file and method describing its purpose and single line comments may be placed with code blocks where required. Avoid too many comments and copy-pasting code in comments.  

“When you see commented-out code, delete it!”

Robert C. Martin, Clean Code

• Follow Object-Oriented Principles. Adopting object-oriented concepts in programming makes the code modular and cohesive, which improves code readability and maintainability. Object-oriented programming is based on how a human mind perceives objects in real world, therefore a software program implemented using object-oriented principles is likely to be more understandable. 

• Organize Code in Folders and Packages. Organizing the source code in appropriate file and folder structure makes it pretty neat and understandable. Adding code to one master file makes it huge and unmaintainable. Typically the framework or IDE saves different file types in a standard folder structure.

Android Studio IDE Folder Structure