Project

General

Profile

Coding standards and hints for Virtuemart » History » Version 12

Max Milbers, 02/18/2014 04:11 PM

1 1 Max Milbers
h1. Coding standards and hints for Virtuemart
2
3 3 Max Milbers
In general we avoid the use of globals. Globals are hard to maintain and they are unsure variables. 
4
5 1 Max Milbers
h2. Code Formatting:
6
7 12 Max Milbers
We follow the joomla standard in most cases. We use camelCase for methods. For faster copypasting and working with database fields, both variable and database fields are lowercase and seperated with "_". You may use for internal variables camelCase also. 
8
We prefer for any if/else constrution clear brackets. Clear and simple "one line if" constructions are allowed, but in case there is an else use curly brackets.
9 1 Max Milbers
10
Example:
11
12
<pre>
13
function exampleMethod($data = 0) {
14 12 Max Milbers
15 1 Max Milbers
    if (!$product_id) $product_id = JRequest::getInt('product_id', 0);
16 12 Max Milbers
17 1 Max Milbers
    if ($product_id > 0) {
18
        ...;
19
    }
20
}
21 12 Max Milbers
</pre>
22
23
Templates keep the open and closing tags <?php and ?> in one line. Avoid closing and direclty opening again. Prefer always plain html without echoing whole lines (just echo the variable instead)
24
<pre>
25
<?php if ($link) { ?>
26
    <a href="<?php echo $link; ?>">My link</a>
27
<?php } ?>
28 1 Max Milbers
</pre>
29
30
h2. SQL Formatting:
31
32
The queries should follow this format:
33
34 10 Max Milbers
@$q  = 'SELECT `example_id` FROM  `#__vm_table` WHERE `user_id`= "' . (int)$user_id . '"';@
35 1 Max Milbers
36
or if the
37
38
$user_id is an array, use $user_id["myId"]
39
40
Placing of the ` improves speed, because the sql-engine can parse faster ( and do not have to reparse).
41
42
h2. Variable Formatting:
43
44
Due abstract logic many people name their variables or database fields just "id", "key", "value" and so on.
45
46
In our case we want to rewrite the structure of an old code, therefore it is very important to find the variable in the code rather fields in the database.
47
48
So we want a kind of this: <classname><tablename>variable like here
49
50
$vendor_id or $payment_method_id
51
52
Exception from this rule is the use of ordering and published. Ordering and published with 0 and 1 as values are useable with the joomla standard methods.
53
54
h2. Filename Formatting:
55
56
Filenames should be lowercase.
57
58
Models filenames (mymodel.php), view direcorynames (myview), all helper files and probably all other files loaded by the Joomla Framework, must be lowercase, no matter how you load the file:
59
60
 @$this->loadHelper('adminMenu'); // looks for the file helpers/adminmenu.php@
61
62
More complex filenames that are specific to your task and loaded by your own code (using require_once()), e.g. mySpecificClass.php, can be camelcase.
63
64
Read this article for more info http://docs.joomla.org/Talk:Developing_a_Model-View-Controller_Component_-_Part_1#Use_lowercase_file_and_folder_names_in_your_components.21 
65
66
h2. URL Requests:
67
68
As written in the section __Filename Formatting__ above, Joomla requires lowercase filenames. However, URL requests are not lowercased by Joomla. In order to find the proper views and controllers, make sure you use lowercase only in requests, e.g.:
69
70
  $this->setRedirect('index.php?option=com_virtuemart&view=updatesMigration', $msg); // Fails
71
$this->setRedirect('index.php?option=com_virtuemart&view=updatesmigration', $msg); // Works
72
73
74
h2. Character Encoding:
75
76 11 Max Milbers
Like in joomla we use UTF-8, without BOM. Please ensure the right character set in your IDE.
77 2 Max Milbers
78 6 Max Milbers
h2. Path constants
79 1 Max Milbers
80 6 Max Milbers
Always use:
81
82
JPATH_VM_SITE for the frontend (points to JPATH_SITE.DS.'components'.DS.'com_virtuemart')
83 1 Max Milbers
JPATH_VM_ADMINISTRATOR for the backend (points to JPATH_SITE.DS.'components'.DS.'com_virtuemart')
84
85
This is important for performance and that all pieces of code work in every application that means, plugins, modules and so on.
86
87 7 Max Milbers
h1. Database tables and fields
88
89
h2. Naming convention
90
91
In general we follow now the nooku conventions for naming tables and fields (http://nooku.assembla.com/spaces/nooku-framework/wiki/KDatabase). 
92
93
All tables must start with the component name, here virtuemart => #__virtuemart_ and be lowercase.
94
95
All non xref tables should use plural. Don't use underscore to make long words readable. Concat them like the germans do, for exampel:
96
vm_user_info => virtuemart_userinfos, vm_admin_menu => virtuemart_adminmenu, vm_payment_method => virtuemart_paymentmethods, ...
97
98
All xref tables are now added with underscore, the use of singular or plural gives a hint on the kind of the xref.
99
For exampel the xref table linking products to categories looks like #__virtuemart_product_categories. Or the hardcore exampel category_categories :-).
100
101
Next is to consider that all primary keys should be always the table name in singular + id on it. Look on this as exampel
102
103 8 Max Milbers
  CREATE TABLE IF NOT EXISTS `#__virtuemart_product_categories` (
104 7 Max Milbers
  `virtuemart_product_id` int(11) NOT NULL DEFAULT '0',
105
  `virtuemart_category_id` int(11) NOT NULL DEFAULT '0',
106
107
108 1 Max Milbers
h2. Standard publishing fields use:
109 9 Max Milbers
110 7 Max Milbers
Except the published field we use now the nooku conventions. So we use   
111 1 Max Milbers
112 7 Max Milbers
  `ordering` tinyint(2) NOT NULL,
113
  `shared` tinyint(1) NOT NULL,
114
  `published` tinyint(1) NOT NULL DEFAULT '1',
115
  `created_on` datetime NOT NULL default '0000-00-00 00:00:00',
116
  `created_by` int(11) NOT NULL DEFAULT 0,
117
  `modified_on` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
118
  `modified_by` int(11) NOT NULL DEFAULT 0,
119
  `locked_on` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
120
  `locked_by` int(11) NOT NULL DEFAULT 0,
121
122 2 Max Milbers
- publish_up and publish_down formatted in the db as datetime with standard 0000-00-00 00:00:00
123
124
The standard query is then 
125
126 5 Max Milbers
	@ $db = &JFactory::getDBO();
127
	$this->_nullDate = $db->getNullDate();
128
	$this->_now        = JFactory::getDate()->toMySQL();
129
130
 $query  = 'SELECT * FROM `#__sometable` WHERE yourexampel ="myexampelvalue" AND ';
131
 $query .= ' ( publish_up = '.$this->_db->Quote($this->_nullDate).' OR publish_up <= '.$this->_db->Quote($this->_now).' )' .
132
 ' AND ( publish_down = '.$this->_db->Quote($this->_nullDate).' OR publish_down >= '.$this->_db->Quote($this->_now).' ) '; @