Dolphin Code Convention
When working with Dolphin code, developing extensions and modifications, the following code convention is advised to be followed.
You should write clean, readable code. It's recommended you follow the guidelines posted here. You should also keep structure in mind, and take advantage of extra white space to increase readability.
You should also comment your code so others can understand what you are trying to achieve.
In addition to the above, the following should also be kept in mind when messing with templates and other related voodoo.
You should take advantage of Dolphin's page system when possible, and keep your content within page blocks. You should also use the default design box when using page blocks.
You should also keep HTML and CSS in a template and not within the code itself.
HTML
Your HTML should be written in a readable manner. You should use proper indentation for structure, like so:
<body> <div id="header"> <div id="logo"> <img src="images/logo.png" alt="logo"> </div> </div> </body>
You should take advantage of the default class attributes as defined in the uni template. You should keep the use of custom classes and id attributes to a minimum.
CSS
Your CSS should also follow a set of standards, which ensures readable code. Blocks should be organized like so:
selector {
property: value;
}
The following should be noted about the above:
- Each selector should be on its own line, with an empty line separating each.
- Each property should be on its own line, with a single indentation.
You should also list properties alphabetically, like so:
selector {
background-color: #fff;
color: #333;
}
Vendor-specific properties (e.g., -moz-border-radius) should precede their generic counterpart.
It's encouraged you check your (X)HTML and CSS against the W3C's validator services:
http://jigsaw.w3.org/css-validator/
Class Names
All Class Names must begin with the prefix, and each word with a capital letter to avoid identical names and to make more unique classes written by the given developer.
Example:
BxMyClassName
Variable Declarations: Names
Given no strict data classification in PHP, all Variable Names must begin with a lower case letter of the first character in the name of a particular data type prefix.
Data type prefixes:
- i Integer
- f Float, Double
- s String
- a Array
- r Resource
- b Boolean
- is Boolean
Following the first letter every word used in the Variable Name must begin with a capital letter.
Example:
$sName = "Variable Value";
$iCnt = 0; $iCnt++;
$rMyFile = fopen ("myfile.txt", "r");
var $isWritable;
Function Declaration: Names and Formatting
All Function Names should start with a lower case letter, and each word should begin with a capital letter. Curly braces used in the list of parameters must be given on a new line instead of following the brackets.
Example:
function myFunction($iNumber, $sName)
{
//code is here
}
Language Structures Formatting
Language structures such as if ... else, for, foreach, while, etc. must be presented in the following manner:
- To provide better readability of the code, there should be a space between the name of the structure and the following parenthesis
- For the same reason, statements concluded within the brackets should be separated with a break
- A similar rule applies to ternary operator
- There is no space after the left parenthesis and before the right parenthesis
- Open curly brace must be on the same line, and closing curly brace must be on the new line
Example:
foreach ($aNames as $sKey => $sVal) {
//code here
}
switch construction
- The above rules must be applied for the switch construction itself.
- The inner case-statements should be indented with the tab.
- The inner case code should also be distinguished with an additional tab.
Example:
switch ($iNumber) {
case 1: //code here break;
case 2:
//code here
break;
default:
//code here
}
Writing Your Own Code
You should avoid making changes to core files where possible. If you make any changes to core files, these changes should be outlined in two ways:
- Stating the start and end positions of changes
- Including all modified files in a changes.txt file
When writing your own code to modify the original script, it must be thoroughly commented to be easily distinguished from the original code.
/* Start [Extension] by [Developer] */ [Code] /* End [Extension] by [Developer] */
You should include a changes.txt file with all changes like so:
/modules/boonex/groups/classes/BxGroupsVoting.php /templates/base/scripts/BxBaseMenu.php
It's encouraged you make known on your product page whether the product is an extension that requires overwriting or editing core files. It's also encouraged that you include the changes.txt file somewhere in your description. It's highly recommended to leave the original script untouched when modifying the code. All the functionality of the extension must be saved in separate files instead of the original code. The files with functionality of the modified product must be combined into a separate folder appropriately named (extension name). Each folder should follow a system of docs i.e. cataloging to keep all pictures in the folder "images", stylesheets - in "css" folder, etc.
Database Tables
Tables used in the extensions must be named with the prefix (vendor and extension name).
Example
super_blog_posts, super_blog_comments
Where super_ is vendor prefix of "Super Programmers" company and blog_ is module prefix of "Blogs" module.
