IBSng Coding Convention

General

• Use extra new lines to separate different blocks of code.

File Names

• File names should be lower case seperating multiple words with underline _.
• Directory/Package names follow the same rules.

Variable Names

• Variable should be written in lower case. If it consists of multiple words, seperate them with underline _. ex: user_obj, user_id
• Don't use single letter variable names except where they are very obvious (ex. c as count or i,j as loop counter)
• Use obvious variable name. Smaller variable names are preferred until they are obvious about what they are.
• Use _obj suffix for object variable in Python/PHP/JS codes
• Use s suffix for list or dictionaries that contain multiple values of same entity. ex: users for a list of user instances
• In PHP String always enclose variables names with {} ex. {$username}

Method/Function Names

• Method names should writter in lower case letters. If consist of multiple words, the first letter of each word except first should be written in upper case. ;ex: getUserInfo, listUsers
• For private methods use __ prefix and for protected methods use _ prefix for method name.
• a comma and an space should separate arguments while calling a function ex. add($a, $b)

Class names

• Class names should have first letter of all words including first word in capital and other letters in lower case. ;ex: User, BWLeaf

Comments

Python

For python use pydoc format comments for classes and methods.

def getTree(self, interface_name):
        """
            get tree nodes for interface_name
            for each node there's a list containing 3 members.
            the first is node_id second is list of child nodes and third is list of child leaves
            each child node is a list of same format. Leaves are leaf_name s only
        """
        int_obj=bw_main.getLoader().getInterfaceByName(interface_name)
        return self.getSubTree(int_obj.getRootNodeID())

For in-method comments use normal hash marks #, before the place you want to comment

PHP/JS

Always use multi line style comments for commenting methods/classes. Put the comment before the definition

    /*
        Add new checkbox object to container
    */
    CheckBoxContainer.prototype.add=function(check_box_obj)
    {
        this.check_box_objs.push(check_box_obj);
        check_box_obj.onclick=checkBoxOnClick;
        check_box_obj.container=this;
    }

inline comments can use both single line and multiline comments, but put them in the line before the entity you want to comment

Lines

• Always break lines longer than 110 characters
• Use new lines to separate logical parts of function/method codes

Documentation

Descriptions are added to the code for the distinct purpose of documenting the code to assist other people in understanding the code's logic. Always follow the standard documentation. For Class/Method/Variables add descriptions before definition :

/**
 * MyClass description.
 */
class MyClass {

    /**
     * Description
     * @var $var
     */
     
    var $var;
    /**
     * MyFunction description.
     * Second line for description.
     *
     * @param type $var1 : description for $var1
     * @param type $var2 : description for $var2
     * @return type : description for returning value
     */
    function MyFunction($var1,$var2){
        .
        .
        .
        return (...);
     }
}

If you are passing a Class object to another function , make a comment before use like this :

/* @var $obj_var MyClass */
$obj_var->(...);

Good to Read

http://www.python.org/dev/peps/pep-0008
http://en.wikipedia.org/wiki/PHPDoc