Software Development Resources
Create account | Log in | Log in with OpenID | Help

Readability

From DocForge

Code readability is the subjective measurement of how well code explains what it's doing. Highly readable code would be very easy for a programmer to understand without any further explanation. In contrast, unreadable code requires more documentation to explain its design and implementation to others.

Readability has no direct impact on application performance. It relates only to human interpretation of programming logic. Overly verbose code, however, can result in more lines of execution depending on the programming language and compiler / runtime.

[edit] Benefits

Easily readable code is easier to debug and maintain. Programmers familiar with the code can retrace the logic quicker and those unfamiliar with the code can learn its structure and intent without additional help. Therefore readable code reduces a system's maintenance costs.

Theoretically, readable code requires less documentation. This theoretically can reduce development costs. But even easily readable code can use additional documentation to explain what the programmer was thinking or why certain actions were chosen.

[edit] Improving Readability

To improve the readability of code:

  • Follow common coding standards:
    • Use descriptive variable and function names. Avoid shorthanded names like x or o() where more descriptive names could be used, such as price and output().
    • Avoid excessive shorthand code. Many programming languages provide multiple ways for coding the same thing. Too many tricks, especially when nested, make it harder for a person to quickly identify what the code is supposed to do.
    • Indent properly and consistently.
    • Add code comments for any code segments which aren't easily understandable. Often simply explaining why a code segment exists (as opposed to only describing what it does) can greatly increase readability.
  • Prefer local variables over global. Global variables might be altered anywhere, in expected places. Tracing through such logic can be confusion.
  • Avoid using too many "magic" methods or hidden hooks. Some languages, runtime environments, and frameworks allow special functions to be defined, to be called automatically rather than explicitly by the developer. If a programmer does not see these hooks, they may not immediately realize why a particular action is taken or a value is altered.
  • In object oriented programming languages, having many nested interfaces or abstractions can be confusing. For example, if a developer needs to look back over 10 class definitions to understand how an object works, each altering the same properties, it can become difficult to trace.

Discuss