The Right Mind - Stylize

One of the most important aspects of coding visually is your coding style. Each person chooses his own style, but good coding style is always readable and consistent. In this post I will share with you my own coding style, separated to elements.

Naming

One of the most important elements in understandable code is variable names. Let's look at the wrong way to do it.

if($var1 <= $var2){
    funcOne();
}

What can you gather about what the program will do in funcOne() from this code? Probably nothing. Now let's look at a better way to do it.

if($nextLoginTime <= $currentTime){
    login();
}

Isn't this much better? Without any amazing knowledge in programming you can know right away that the given code will check if the next login time passed, and login if it did.

When writing programs, whether it is compiled C# or C++ code, or open source PHP code, I always try to keep the names of the variables, classes, namespaces and functions relevant to their functionality and contents. This way even after a year, I will read my own code easily.

Indentation

Indentation helps to understand the hierarchy and structure of your code. I use tabs to indent any code that logically belongs to another piece of code.

PHP Examples

function someFunction(){
    ...

    if($success = false){
        runFunction();
    }

    ...
}

class someClass{
    private $privateVariable = null;
        function get_privateVariable(){
            return $privateVariable;
        }
        function set_privateVariable( $newValue ){
            $privateVariable = $newValue;
        }

    public $publicVariable = null;

    function someFunction(){
        ...
    }
}

Note that even though the functions get and set for the private variable are not located in between curly brackets, I still indent them, because logically they are just a small subset that belongs to the variable.

Commenting

Commenting may seem tiring and unnecessary at first, but after it becomes your second nature, you can really appreciate it.
I take it as a rule to insert both comments that help reading the code, and comments that describe, functions, classes and variables and are phpDoc compliant for PHP ( SharpDevelop also has similar documentation style for C# ).

While you may not want to comment so extensively, I do recommend you to take as a rule to comment everything that may take more than a moment to figure out while skimming the code.

For instance, compare the following two code fragments.

...
if(preg_match( "/^[a-zA-Z0-9._-]+@[a-zA-Z0-9-]+\.[a-zA-Z.]{2,5}$/", $string ))
    nextStep();
}
...

...
// If the string is a valid email address, move to the next step
if(preg_match( "/^[a-zA-Z0-9._-]+@[a-zA-Z0-9-]+\.[a-zA-Z.]{2,5}$/", $string ))
    nextStep();
}
...

You have to admit that you can't easily skim through the first fragment without wondering, and then stopping to figure out what the regular expression does, while reading the second fragment's comment saved you this time.

Tabular Variable Assignment

When there is a big list of variable assignments, I always prefer to have them in a table like structure. The following fragment is an example from a C# application.

    public firebirdConnection( string newServer, string newDatabasePath, string newUser, string newPass){
    this.server    =    newServer;
    this.path      =    newDatabasePath;
    this.username  =    newUser;
    this.password  =    newPass;

    ...
    }

The function starts with four variable initialization assignments. By formatting them into a tabbed structure, I make them more readable.

Consistency - Brackets, Function Operators, Spaces e.t.c

Aside from the other rules above, I also set myself a general style according to my own personal taste. I try to always keep all my code consistently formatted with this coding style.

Below is a quick summary of those rules.

    // First curly bracket is always on the same line with it's function or statement.
    // There is a padding one one space within the function declaration or calling brackets, and there is a space after the comma.
    function doThis( $operator, $anotherOperator ){
        // No space within if, for or other statement brackets
        if($condition == true){    
            // Functions with lots of operators have a line break after each comma
            login( $username,
                   $password,
                   'www.server.com',
                   1234 );
            ....
        }
        ...
    }