Let me teach you about coding professionally!

[Dave]

Hello,

This is the first of many short articles/tutorials from me. Today we will be looking at professional coding standards. Read on, and enjoy.

The term "professional coding standards" relates to writing language instructions using clear, readable blocks of text, which include professional use of naming conventions, comments and multimedia compatibility. Let's break down each of these to learn more.

Naming Conventions

These are rules that help to determine the pattern for naming identifiers (variables, attributes etc) in the source code. Good use of naming conventions reduces the amount of effort required in understanding code and helps to make it more readable, compared to having excessively long names or very short abbreviations.

Let's have a look at two examples. The first example shows BAD use for naming variables and such. The second shows PROFESSIONAL use. PHP has been used for the following examples.

$s = "Hello world";

$message = "Hello world";

The second example gives us better understanding of the variables' use. We know it is a message of some sort to be outputted. In the first example $s could stand for anything and gives no indication.

There are many different types of Naming Conventions that are used in programming. The most popular and recommended notation is the Hungarian Notation, which identifies the purpose or type in the variable name by capitalizing keywords.

An example of using the Hungarian Notation would be as follows.

$emailSubject = "Free holidays";

In the above example, "email" and "subject" have been separated by capitalizing the S. This shows that subject is related to an email. This gives us very good indication of what the variable is all about.

The same use applies to naming functions/methods. It is better to have a function called output than one called o, right?

Professional use of Naming Conventions helps to reap the following benefits.

• Provides additional information about a variable/function
• Maintains consistency in a team of engineers
• Improves the appearance of the source code, making it look more professional
• Better quality variable dictionary's for project documentation
• Easier to remember, makes searching massive scripts in text editors a breeze
• Productivity. Makes debugging and testing software a lot easier.

But isn't there still something missing..? Of course there is, comments!

Comments

Comments are used to describe certain portions of code, sometimes along with their pre-post conditions and post conditions. There are three key areas in any software file where comments are an essential asset.

1. At the top of the file, where we describe the general purpose of the software along with vital pieces of information such as the package name, author, version number, revision date and license
2. To describe the purpose of a specific function/method
3. To describe important script variables

The comments at the top are very important. They let others who view the code know what its all about, its name, who wrote it, what version of the code they are viewing and so on. This is very important information because it provides everything other developers NEED TO KNOW about your software. If you don't provide comments then how can you expect to have professional collaboration between team members?

Let's take a look at an example of PROFESSIONAL commenting for the top of a file.

<?php
/**
 * This script contains useful methods for retrieving the contents of
 * a website, including the title, anchor links and images. It uses cURL to
 * retrieve the data and regular expressions to help match title, image
 * and anchor tags.
 *
 * @package Website Content
 * @author Fred Bloggs <[email protected]>
 * @version 0.0.1
 * @revision 12-May-08 16:40 GMT
 */
?>

I am sure most of those are pretty self explanatory. Package relates to the name of the package (software) this file/script is associated with. Author is the engineer who wrote it. But what about those other two? Let's go into a bit more detail.

Version - Many of you are most likely thinking, "Huh? why are you going into detail about version numbers!!?". Well let's be honest, how many of you actually know a logical way of determining the version for your software? And how many of you know the reasons for using version numbers? Well let me tell you.

A version number is actually read as [major].[minor][.maintenance] . The version number relates to the development progress your current major release of your software is. In the above example it shows as release 0, with no major or minor functionality and its first revision. Lets break down the three sections.

[major] - If this is a 0 then it usually refers to the software being in Alpha or BETA stage. Anything greater (1, 2, 3) relates to the latest major release of the software. This value will increment by 1 when there are significant improvements to the software. Significant improvements relate to the implementation of new features of the software or a complete revamp in design.

[minor] - This relates to minor or small improvements in the software, such as adding an additional few instructions for small things.

[maintenance] - This is incremented when bugs or errors in software are fixed.

In the comments, revision relates to the last time the file was revised (updated).

Version numbers and revision dates help aid with debugging bug reports and such.

The other important areas for commenting are for functions and variables. Function comments should clearly state the purpose of the function, what the various parameters are and what the return type should be.

Multimedia Compatibility

This relates to being able to view source code in different text editors and environments without causing the code to be spewed out all over the place. Let's never forget not everybody uses the same resolution or text editor, so we have to do our best to adapt to as many as possible.

The most important factors to consider are line lengths and white spaces. You should always indent blocks of code using SPACES (not tabs!!) to help them stand out clearly when being viewed across different editors and environments. Again, it makes for far more readable code because we know exactly where everything is without worrying about getting lost in a muddle of messy code.

Minimal line lengths help when viewing code on different resolutions. Sure, you maybe able to see a million characters on your uber awesome 5000 x 5000 resolution but what about that other poor developer who only has an 800 x 600 screen and word wrap on in his text editor? Uh oh!! The recommended
maximum line length is around 80 characters.

Let's look at a final example that puts together everything we have learned in this article and use indentation.

<?php
/**
 * This script contains useful methods for retrieving the contents of
 * a website, including the title, anchor links and images. It uses cURL to
 * retrieve the data and regular expressions to help match title, image
 * and anchor tags.
 *
 * @package Website Content
 * @author Fred Bloggs <[email protected]>
 * @version 0.0.1
 * @revision 12-May-08 16:40 GMT
 */

class WebsiteContent
{
    /**
     * The title of the website.
     * @var string
     */
    private $title = "";

    /**
     * getTitle. Returns the title of a web page.
     *
     * @param void
     * @return string
     */
    public function getTitle()
    {
        // ....assume we get it here...
        // and then an example of inner block
        if($title)
        {
            return $title;
        }
    }
}
?>

Good use of commenting and naming conventions really help spice up your code and make it more clearer and readable. It also helps maintain professional work ethics and standards in an organizational structure and improves productivity.

Thanks for reading and I hope you enjoyed. This article really only covers the bare essentials about professional standards. To read more about topics covered here check out the links below.

Learn more about NAMING CONVENTIONS

Learn more about SOFTWARE VERSIONS

:bingo:

 

[Keral_Patel]

Very good one

I still remember about Microsoft standards that I read a while back when appearing for MCSD exams.

Some examples:

String variable = $strName
Integer = $intNumber
Boolean = $boolCorrect

Also helps other people in your project to understand what the variable is and how will it react if used in his part of code.

 

[ChosenDigit]

Hi DomainMan, I will definitely join your class. I am actually looking for the section to introduce myself, but I popped into your class first. When is the next session?

 

[wikes82]

Great tutorial.. though, I love to obfuscate my codes :hehe:

 

[R9V.com]

I wish I was smarter - God; why must you curse me with beauty as my only trait!!!


*joins class too*

 

[psalzmann]

Great tips! I use to use the $message = ""; in double quotes but lately I've been doing it with single quotes. This allows me to write some html without having to escape my double quotes.

Here's an example:

BAD:
$message = "<a href=\"link.php\">some link</a>";

GOOD (or better)
$message = '<a href="link.php">some link</a>';

Regards,
Peter

 

[xrvel]

Nice information. I didn't know about comment convention before :tu:

 

[Aceredbaron]

Looking forward to your lessons sir
Thanks

 

[Li Weng]

Thanks. Is there lesson 2?

 

[Dozi Domains]

I have joined the classroom too, sitting in the backrow. :cy:

 

[Lio]

waoooooo....

i want to join in ur class too...

waiting mode on..[/B]