First the comments, then the code

In this article I want to talk about a topic that is very close to my heart and that many developers seem to leave on the back burner. This topic represents not only an undeniable “best practice” in the way of developing code, but also a form of respect towards the community of developers and engineers who will have to put their hands back on code written by someone else: I am talking about code comments.

A very dear university professor of mine, Prof. Carlo Gaibisso, used to say this phrase in his lectures on “Structured Programming” in the C language: “You write the comments first and then the code.”

How can you blame them?

Despite the fact that programmers are a class of “stage animals” in the world of computer science, and despite the training a developer may have, it is a fact that it is always easier and more immediate to read something that belongs to our common way of communicating. It is much easier to read in Italian what an algorithm is about than to understand what an algorithm written in code does; it becomes the more complex to understand it the more complex the algorithm.

Object-oriented programming also incorporates procedural programming. Within the methods of a class, one programs procedurally.

Procedural programming is so called because code is executed according to a procedure. I can write procedures for anything… For example if I have to calculate the Fibonacci succession I know that to calculate the number at step n I have to take the previous number and add it to the still previous number.
Therefore the procedure will be: starting with S = 1 1, f3_– > I take _f2 I add it to _f1, and I get

S = 1 1 2

I take _f3 = 2 I add it to _f2 = 1 and get

S = 1 1 2 3

I take _f4 = 3 I add it to _f2 = 2 and get

S = 1 1 2 3 5

You will understand that it is much easier to instantly understand the definition, “To calculate the nth number of the Fibonacci sequence I add the previous two” than _fn = _fn-1 + _fn-2 especially if this formula is written with variables and cycles within a computer algorithm!

PHP example for calculating Fibonacci series without comments

[php]<br />
<?php<br />
class Fibonacci<br />
{<br />
public static function calculateSuccession($n)<br />
{<br />
$n = $n – 2;<br />
$a = 1;<br />
$b = 1;<br />
echo $a . “
”;<br / >
echo $b . “
”;<br / >
for ($i = 0; $i < $n; $i++) {<br />
$c = $a + $b;<br />
echo $c . “
”;<br / >
$a = $b;<br />
$b = $c;<br />
}<br />
}<br />
}</p>
<p>Fibonacci::calculateSuccession(1000);<br />
[/php]

PHP example with comments

[php]<br />
<?php</p>
<p>/**<br />
* Fibonacci is a class for calculating the Fibonacci succession<br />
* and its verification<br />
*<br />
* Fibonacci is a class for calculating the Fibonacci succession<br />
* The verification of the golden ratio through the relationship between successive terms<br />
* verification by tartaglia triangle and verification by<br />
* Cassini, Catalani and D’Ocagne’s equalities<br />
*<br />
* @author Simone Renzi<br />
* @version 1.0<br />
* @access public<br />
* @see http://renor.it<br />
*<br />
**/<br />
class Fibonacci<br />
{<br />
/**<br />
* @method calculateSuccession – Static method to calculate succession<br />
* of Fibonacci for $n terms<br />
* @param int $n – The number of iterations<br />
* @return void has no return values, it just prints the values<br />
* of the series at each iteration<br />
* @access public<br />
**/</p>
<p> public static function calculateSuccession($n)<br />
{<br />
//As I have two fixed parameters I remove them from iterations<br />
$n = $n – 2;<br />
$a = 1;<br />
$b = 1;<br />
//Print the two starting parameters<br />
echo $a . “
”;<br / >
echo $b . “
”;<br / >
//Cycle for $n<br />
for ($i = 0; $i < $n; $i++) {<br />
//Calculate the value of the subsequence at step $n<br />
$c = $a + $b;<br />
//Print on screen the value<br />
echo $c . “
”;<br / >
//move variable values<br />
//f2 becomes f1<br />
$a = $b;<br />
//f3 becomes f2, the next iteration will calculate the new f3<br />
$b = $c;<br />
}<br />
}<br />
}</p>
<p>Fibonacci::calculateSuccession(1000);<br />
[/php]

I can continue to apply the procedure of taking the previous two numbers to infinity. Obviously computing an infinite set of numbers takes an infinite amount of time so we opt to find the subsequence at term n where n is the number of iterations for which the algorithm will have to perform the procedure.

From the pictures we can see that writing commented code in a virtuous way requires many more lines and therefore more time but in case of maintenance everything will become extremely easier and faster. We invest a small part of our time before so that we do not have to waste whole days afterwards.

Procedures

I can apply a procedure in any context, even for cooking. A recipe is nothing but a procedure: take a saucepan, put 2 tablespoons of extra virgin olive oil, add a clove of garlic, a hot pepper, turn on the stove and simmer, etc.

Procedures are inherent within functions and can be combined to solve larger problems. Returning to the Fibonacci example, another algorithm might verify that the ratio between two consecutive numbers in the Fibonacci series approximates as n increases more and more the golden ratio. A further function could verify that the obtained succession of n terms considering the of the terms on each diagonal of the tartaglia triangle corresponds to the Fibonacci succession, etc.

On par I could say that the previous procedure useful for preparing the soffritto should be carried out on par with the procedure for cooking the pasta.

As you may have realized, a procedure is best and most quickly understood if there are comments describing the steps.

It is usual to insert comments first and then code because this practice allows us to write code very quickly without forgetting anything and leaving other programmers who will have to integrate other functions to quickly understand the famous “what is needed for what.”

[starbox]