TUTORIAL: Keeping the Source Clean

  • Bogey
  • Bogey
  • Genius
  • Bogey
  • Posts: 8363
  • Loc: USA

Post 3+ Months Ago

Introduction


Even though it may not seem like it, but the source is important for programmers, so the way you write your program and how you organize the code... matters. This tutorial is going to cover that for all people having a basic knowledge of PHP.

The Source


There are a couple of important features a good program should have... the one and foremost important feature is that the program actually works the way it is supposed to be. The second important feature of a good program is the way it is written and how the source is organized.

Why? So it would be easy for the programmers to read the source and follow the logic of the script. If corresponding braces are lined up, nested loops indented and variables, functions and classes are named correctly, it would be a breeze updated/re-factoring code for programmers... especially for those who are editing a script that they didn't write.

A clean and well organized source is also good for the costumer since they could find a programmer who would be able to edit it.

Now, what do I consider a clean and well organized source? It is better to explain it with an example:
PHP Code: [ Select ]
<?php
function addition()
{
    // Getting array of passed arguments
    $args = func_get_args();
   
    // Initiating the return value
    $return = 0;
   
    // Looping through every argument and doing the code
    foreach ($args as $key => $number)
    {
        // Making sure we aren't working with an array (Associative Arrays are not allowed)
        if (is_numeric($number))
        {
            $return += $number;
        }
    }
   
    return $return;
}
?>
  1. <?php
  2. function addition()
  3. {
  4.     // Getting array of passed arguments
  5.     $args = func_get_args();
  6.    
  7.     // Initiating the return value
  8.     $return = 0;
  9.    
  10.     // Looping through every argument and doing the code
  11.     foreach ($args as $key => $number)
  12.     {
  13.         // Making sure we aren't working with an array (Associative Arrays are not allowed)
  14.         if (is_numeric($number))
  15.         {
  16.             $return += $number;
  17.         }
  18.     }
  19.    
  20.     return $return;
  21. }
  22. ?>

I would like to point your attention on the features of the source that make it well organized and clean.
  • Corresponding braces (opening and closing for the if statements and the loop) are in line vertically
  • The IF is nested inside of the loop, so it is indented a little more from the margin
  • The open braces for the statements and the loops are one space after the statement/loop decleration (if ()).
  • The source is kept clean by using Assignment Operators ($return += $number; instead of $return = $return + $number;)
  • The source is also commented to let other programmers know what you are doing.
  • Their is no extra coding to make the script take a long time

Yes, that code could be easily modified to be four lines smaller... let me show you:
PHP Code: [ Select ]
<?php
function addition()
{
    // Getting array of passed arguments
    $args = func_get_args();
   
    // Initiating the return value
    $return = 0;
   
    // Looping through every argument and doing the code
    foreach ($args as $key => $number)
        // Making sure we aren't working with an array (Associative Arrays are not allowed)
        if (is_numeric($number))
            $return += $number;
   
    return $return;
}
?>
  1. <?php
  2. function addition()
  3. {
  4.     // Getting array of passed arguments
  5.     $args = func_get_args();
  6.    
  7.     // Initiating the return value
  8.     $return = 0;
  9.    
  10.     // Looping through every argument and doing the code
  11.     foreach ($args as $key => $number)
  12.         // Making sure we aren't working with an array (Associative Arrays are not allowed)
  13.         if (is_numeric($number))
  14.             $return += $number;
  15.    
  16.     return $return;
  17. }
  18. ?>

What happened there is that I removed the braces for the loop and the if statement. You can do that if the loop has only one line of code and if the conditional statement only has one line following after it, otherwise you need the braces.

Even though you can do that and it is easier for the lazier people to do it that way, I really don't recommend that, since it breaks the logic of the code. (I am found guilty of being this lazy though... I'm no one to judge :lol: )

The reason that I don't recommend this is because it breaks the logic of the code (as I already have mentioned). The braces are supposed to tell when the if statement starts and ends, and it would also be easier for other programmers if the braces are already there if they need to add more lines to the condition or the loop.

Conclusion


So, in conclusion you can see that my first example is more correct (in the sense of source organization) then the second example even though it is four lines longer. Sometimes the length of the code doesn't determine how organized the source is... in this case, it actually says how lazy the person is :lol:
  • Anonymous
  • Bot
  • No Avatar
  • Posts: ?
  • Loc: Ozzuland
  • Status: Online

Post 3+ Months Ago

Post Information

  • Total Posts in this topic: 1 post
  • Moderator: Tutorial Writers
  • Users browsing this forum: No registered users and 2 guests
  • You cannot post new topics in this forum
  • You cannot reply to topics in this forum
  • You cannot edit your posts in this forum
  • You cannot delete your posts in this forum
  • You cannot post attachments in this forum
 
 

© 1998-2014. Ozzu® is a registered trademark of Unmelted, LLC.