Coding Conventions in Web Development

Today I would like to share with you a grain of my experience, and we’ll talk about coding conventions. Every person who writes code for a long time somehow comes to the question of standardization of the writing style of the code. I think that each of you have already faced the fact that different projects can be written using different rules and styles, and sometimes it’s annoying, and you want some standardization. In other words, coding conventions are a set of guidelines and rules for a certain programming language that recommend programming style, methods and practices for each case of a piece of script written in that language. These conventions usually cover aspects like comments, folders and files organization, indentation, declarations, white space, naming conventions, programming practices and principles, architectural best practices, and so on. We advise you to follow these rules when you write code; it will help to improve the readability of your code and make maintenance easier.

Most of our examples are given in PHP, but it is easily applicable to all other web languages

1. Tabulation

In the beginning, I would recommend you to decide this question: what to use – tabs or spaces? In general, indentation is not a requirement of most programming languages, where it is used as secondary notation. Rather, developers indent to better convey the structure of their programs to human readers. In particular, indentation is used to show the relationship between control flow constructs such as conditions or loops and code contained within and outside them.

I never really understood the Tabs vs Spaces debate. But anyway, I can recommend you to use four spaces instead of a tab. I have a helpful argument about that: when we view and compare codes using different software (for example, we compare two files in Total Commander), tabs and spaces look differently. Just try to indent any two lines of code, the first one with tab, the second with 4 spaces. It will look the same in Notepad++. But then, try to compare this file with it’s backup version (in Total Commander), and you will notice that the tab is longer than four spaces (in the result, we can get badly formatted code). Thus, please adjust your program to use four spaces instead of tab when you push the ‘TAB’ key. It will help you in the future.

2. Class Names

To avoid repetition of names and to make more unique classes written by the developer, the class names must begin with a certain prefix and each word begin with a capital letter. Example:

class MyClassName {
    function MyClassName() {
    }
}

3. Variable Names

Because the strict data typing (in most web languages) is missing (although it is still available), for the convenience, the variable name should begin with a lowercase letter of the first character in the name of a particular data type prefix.

Possible type prefixes:

• i: integer
• f: float / double
• s: string
• a: array
• o: object
• r: resource
• b: boolean
• is: boolean

After the prefix, we can use Camel style (every word used in the variable name must begin with a capital letter). If you need to declare a private variable, you can use the underscore. Examples (PHP code):

public $sFirstName = "some value";
public $sSecondName = "some value";

private $_iVariable;  

$iDigit1 = $iDigit2 = 10;

$oMyClass = new MyClass();

4. Constant Names

Constants are static variables, which means that their values won’t be changed. As usual, we use all capital letters for constants (don’t forget about possible prefixes). Example:

define('PRJ_WEBSITE_URL', 'http://www.website.com/');
define('PRJ_GLOBAL_CURRENCY', '$');

5. Function Declaration (Names and Formatting)

All function names should begin with a lowercase letter, and every word should begin with a capital letter. Curly braces should be given on the same line (after the list of parameters). Example:

function getPropertyValue($sName) {
    // your custom code is here
}
function setPropertyValue($sName, $sValue) {
    // your custom code is here
}

6. Special Structures Formatting

Special structures, for instance: if/else, for, foreach, while, and so on should follow these rules:

• There should be a space between the name of the structure and the following parentheses (for better readability)
• Conditions which are concluded within the brackets should be separated with space (for better readability)
• There is no space after the left bracket and before the right bracket
• The open curly brace is on the same line
• Inner conditions (cases or other code) should be indented with the tab

Examples:

foreach ($aKeys as $iKey => $sValue) {
    // your custom code is here
}

if ($bCondition) {
    // your custom code is here
} else {
    // your custom code is here
}

switch ($sKey) {
    case 1:
        // your custom code is here
        break;
    case 2:
        // your custom code is here
        break;
    default:
        // your custom code is here
        break;
}

7. Database Tables Names

When you create a table, use logically comprehensible prefixes, and separate the words with an underscore. The use of upper case letters – not necessarily. The same applies to the table fields. Example:

CREATE TABLE IF NOT EXISTS `myprj_records_table` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `pid` int(11) NOT NULL,
  `snippet` varchar(128) NOT NULL,
  `description` varchar(255) NOT NULL,
  UNIQUE KEY `id` (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8;

8. The Directory Structure of the Project

When we work in a team, it is important to keep the structure of folders and files in a logical order. Don’t drop everything in a single folder without any organization; it would be a mess. Example:

/root  folder
  /backup
  /cache
  /classes
  /css
  /js
  /media
    /images
    /mp3
    /video

  index.php
  otherFiles.php

Conclusion

In the end, I would like to say that I cannot force you to precisely follow all these rules, I can only advise. In fact, many dev teams prepare and use their own coding convention directives and guidelines, but in any event, our guidelines will be useful to everyone. I hope you enjoy our article. It would be kind of you to share it with your friends. Good luck and welcome back!