Coding conventions in web development

Coding conventions in web development

2 60895

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 script written in that language. These conventions usually cover such 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 language, 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 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 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, it means that its 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 next 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 can not 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!

SIMILAR ARTICLES

Understanding Closures

0 17840

2 COMMENTS

  1. Point 3 is one I personally disagree. There are two reasons for that:

    1. I simply hate those lowercase ‘meaningless’ prefixes (just a matter of likes).

    2. They add extra effort to my brain when dealing with them. When I’m going to use a variable I think “what will I do with it” not “what type is it and then what will I do with it”, having to remember the type a variable to then remember its name is kind of tiring.

    To avoid doing this one just:

    1. Write code in a way that explains itself. Seeing a variable in its context and giving it a good name, makes obvious its type.

    2. Give the variable the shortest scope posible. That way you won’t need to scroll up and see the variable type where it was declared.

    3. Use the comments. They exist to express what the language itself can’t.

    If there is something that strongly typed languages have tought us is that knowing the type of a variable is really important only at a declaration level, you won’t see ‘oThing’ or ‘aList’ variables in Java or C# why, given it’s clear in declaration, would I bother to state the type of the variable during usage?

    Just a personal opinion. :)

Leave a Reply to Jeysson Guevara Cancel reply