PRODUCT FEATURES

Code documenting: why and how

"Perfect" code is supposed to be self-explanatory, with descriptive names, transparent dependencies, and a clear code structure. In practice, this is nonsense.

In this article, we collected some working techniques that will help you deliver "readable" code.

• Just comment

It is always a good idea to leave comments explaining why certain code blocks were written that way. However obvious it may seem to you, others might find it difficult to figure out the code's logic and structure without accompanying notes from the author.

• Use pseudocode - life-saver for non-techies

Pseudocode is an informal language used to describe algorithms. In ClearSQL, it uses the structural conventions of PL/SQL and translates code into a "human" language. Leave notes above code lines either manually or by using Pseudocode Comments Editor to avoid typos and errors. Watch the video for a good example of how it works.

• Get flowcharts for logical options

Flowchart diagrams generated from Pseudocode help you trace the code flow and sketch out the program structure before actual coding even begins. These interactive deliverables are great when exploring new software.

• Measure it (for profs)

Use metrics to calculate your code's maintainability. This technique will help you identify areas for code refactoring and estimate the software complexity.

The general formula for Maintainability Index is

Maintainability Index = MAX(0,(171 - 5.2 * log(Halstead Volume) - 0.23 * (Cyclomatic Complexity) - 16.2 * log(Lines of Code))*100 / 171)

The Maintainability Index threshold lies between 1 and 100 and, according to industry experts, the resulting values may be deciphered as follows:

85 and more: high maintainability / stable clear code
65-85: average / acceptable maintainability
56 and lower: hard to maintain with bad pieces of code

See all these techniques live in the trial versions of our products:

Was this article helpful?