-
Notifications
You must be signed in to change notification settings - Fork 1
/
coding-standards.html
350 lines (308 loc) · 14.5 KB
/
coding-standards.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Dlayer: Coding standards</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="description" content="Dlayer is a web development tool aimed primarily at users that don't have any web design or web development experience.">
<meta name="author" content="G3D Development Limited - Dean Blackborough">
<meta name="application-name" content="Dlayer.com"/>
<meta name="msapplication-TileColor" content="#FFFFFF"/>
<meta name="msapplication-starturl" content="http://www.dlayer.com"/>
<meta name="msapplication-tooltip" content="Dlayer.com: Web development simplified"/>
<link rel="shortcut icon" href="/images/favicon.ico" />
<link rel="icon" type="image/x-icon" href="/images/favicon.ico" />
<link rel="icon" sizes="192x192" href="/images/favicon-192x192.png" />
<link href="/bower_components/bootstrap/dist/css/bootstrap.css" media="screen" rel="stylesheet" type="text/css">
<link href="/css/site.css" media="screen" rel="stylesheet" type="text/css">
<link href="bower_components/prism/themes/prism.css" rel="stylesheet">
<link href="/images/favicon.ico" rel="shortcut icon" type="image/vnd.microsoft.icon">
<script type="text/javascript" src="/bower_components/jquery/dist/jquery.js"></script>
<script type="text/javascript" src="/bower_components/bootstrap/dist/js/bootstrap.js"></script>
<script src="bower_components/prism/prism.js"></script>
<script src="bower_components/prism/components.js"></script>
<script src="bower_components/prism/components/prism-php.js"></script>
<script>
var _prum = [['id', '586d2ba4aa6959fe4202e95f'],
['mark', 'firstbyte', (new Date()).getTime()]];
(function() {
var s = document.getElementsByTagName('script')[0]
, p = document.createElement('script');
p.async = 'async';
p.src = '//rum-static.pingdom.net/prum.min.js';
s.parentNode.insertBefore(p, s);
})();
</script>
</head>
<body>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-64736-3', 'auto');
ga('send', 'pageview');
</script>
<div class="container-fluid">
<nav class="navbar navbar-toggleable-md navbar-light">
<button class="navbar-toggler navbar-toggler-right" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<a class="navbar-brand" href="/">Dlayer</a>
<div class="collapse navbar-collapse" id="navbarSupportedContent">
<ul class="navbar-nav mr-auto">
<li class="nav-item">
<a class="nav-link" href="https://demo.dlayer.com">Try the Demo</a>
</li>
<li class="nav-item">
<a class="nav-link" href="http://blog.dlayer.com/">Development blog</a>
</li>
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Docs and about
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
<a class="dropdown-item" href="releases.html">Changelog</a>
<a class="dropdown-item disabled" href="#">Documentation (moving)</a>
<a class="dropdown-item" href="coding-standards.html">Coding standards</a>
<a class="dropdown-item" href="history.html">The history of Dlayer</a>
</div>
</li>
<li class="nav-item">
<a class="nav-link" href="http://www.deanblackborough.com">DeanBlackborough.com</a>
</li>
<li class="nav-item">
<a class="nav-link" href="http://www.transmute-coffee.com">Transmute Coffee.com</a>
</li>
<li class="nav-item">
<a class="nav-link" href="http://www.g3d-development.com/blog">G3D Development Ltd</a>
</li>
</ul>
</div>
</nav>
</div>
<div class="header">
<div class="container">
<div class="row">
<div class="col-md-12">
<h1 class="display-2">Coding standards</h1>
<p class="lead">Suggestions for contributors.</p>
<p>
<a class="btn btn-secondary" href="https://github.com/Dlayer/dlayer/zipball/master" role="button">Download: Zip</a>
<a class="btn btn-secondary" href="https://github.com/Dlayer/dlayer/tarball/master" role="button">Download: Tar</a>
<a class="btn btn-primary" href="https://github.com/Dlayer/dlayer" role="button">Find on GitHub</a>
</p>
</div>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-lg-12">
<p class="lead">If you would like to contribute to Dlayer, please try to adhere to the coding standards
I have detailed below, if you have any questions or believe I have missed something, please content
me. I am working towards moving to PSR-1/2, there may be minor differences listed below, if unsure
please check with me, it could be an error on this page, or I might have deliberately opted for
something different.</p>
<p>There is an excellent chance that my code, specifically some of the older code; will not match these
guidelines. With all new code, I am coding to the standards, and anytime I touch a file in a
non-insignificant way I am updating the code. However, I am not going through the old code to
update it just for the sake of matching the standards.</p>
<p class="text-muted"><em>I will not turn away any code that does not adhere to these coding standards; I
very much
understand how difficult it can be to change after years of development. I am still adjusting to the
coding standards, and as mentioned they don't apply to a significant amount of the Dlayer
code.</em></p>
<p class="text-muted"><em>Please just try to ensure that your coding style is consistent, that is far more
important
than trying to adhere to any arbitrary rules.</em></p>
<h3>Pull requests</h3>
<p>All pull requests need to made from a branch in your fork, please also try to give your branch a
name that relates to the change/feature you want me to merge. Most importantly, before creating a
pull request, please update your fork, so it is up to date with Dlayer/master.</p>
<h3>Files</h3>
<ul>
<li>Use <code>UTF-8</code> character encoding</li>
<li>Unix formatted, <code>(LF)</code></li>
<li>A line length of <code>120</code> characters, this is not in any way a fixed requirement,
please let context dictate, don't make code harder to read by wrapping it to hit a particular
line length
</li>
<li>All code and comments should be in English</li>
<li>Spaces for all indenting, I recommend <code>four spaces per tab</code></li>
</ul>
<h3>PHP</h3>
<ul>
<li>Please always use <code><?php ... ?></code>, never
<code><? ... ?></code>, disagrees with PSR-1, shoot me!
</li>
<li><code>PHP CONSTANTS</code> should all be in <code>UPPERCASE</code>.</li>
<li>PHP keywords should be in <code>lowercase</code>, including, <code>true</code>,
<code>false</code> and <code>null</code></li>
<li>Braces on their own line for classes, namespaces and functions</li>
<li>Braces in line for if/while etc</li>
<li><code>UpperCamelCase</code> for classes, interfaces etc</li>
<li><code>lowerCamelCase</code> for methods and functions</li>
<li><code>lowercase_with_underscores</code> for multiple word variables</li>
</ul>
<p>I believe it is easier to show coding standards using a visual example, please check the code snippet
below, contact me if you have any questions.</p>
<pre>
<code class="language-php">/**
* This is the comment for the example class, it should
* be a brief overview of the class
*
* @author Name <email>
* @copyright Copyright here
* @license Link to license text
*/
class ExampleClass
{
private $class_property;
/**
* This is a comment for the example method shown
* below, method comments should explain the
* purpose and if helpful the context in which
* it will be used
*
* @param1 array Description
* @param2 boolean Description
* @return void Brief description of returned value if necessary
* @throws \Exception (if relevant)
*/
private function exampleMethod(array $param_one, $param_two)
{
// This is a single line comment
if ($var1 === $var2) {
// logic
}
/* This is an example of a multi-line comment, it
should detail what is happening below and why */
switch ($var) {
case 1:
// logic
break;
case 2:
case 3:
// logic
break;
// Default case statement always included
default:
// logic
break:
}
for ($i=0; $i<$n; $i++){
// logic
}
$multiple_word_var = 'foo';
$quotes = 'Single quotes should be used, only
use double quotes when necessary';
$array1 = array('value1', 'value2');
$array2 = array(
array('value1', 'value2'),
array('value1', 'value2')
)
$sql = "SELECT field_1, field_2, field_3
FROM table_name
JOIN table_name_2
ON condition2 = :value2
WHERE condition1 = :value1";
$stmt = $this->_db->prepare($sql);
$stmt->bindValue(':value1', $value1, PDO::PARAM_INT);
$stmt->bindValue(':value2', $value2, PDO::PARAM_INT);
$stmt->execute();
$model_users = new Model_Users();
return $model_users->activeUsers(30);
return $model_users->activeUsers()
->limit(50)
->order('desc');
}
}
</code>
</pre>
<h3>JavaScript</h3>
<p>The coding standards for JavaScript are as close as possible to the PHP coding standards, below is an
excerpt from one of the JavaScript files.</p>
<pre><code class="language-javascript">
var previewFormBuilder =
{
highlight: false,
changed: false,
visible: false,
/**
* Preview function for integer based field attributes, updates the
* attribute value in on the form as the user makes changes in the tool
*
* @param {Integer} Id of the field being edited
* @param {String} Field attribute being updated
* @param {String} Element attribute that is being updated
* @param {String} Initial value for the text string
* @param {Boolean} If the value is optional the user should be able to
* clear the value, shouldn't default to initial value, if not set
* defaults to false
* @returns {Void}
*/
elementAttributeInteger: function (field_id, attribute, field_attribute,
value, optional)
{
if (typeof optional === 'undefined') {
optional = false
}
$('#params-' + attribute).change(function ()
{
previewFormBuilder.highlight = true;
var selector = '#field_' + field_id;
var new_value = parseInt(this.value, 10);
var current_value = parseInt($(selector).attr(field_attribute), 10);
if (new_value !== NaN && current_value !== NaN &&
new_value !== current_value && new_value > 0) {
$(selector).attr(field_attribute, new_value);
previewFormBuilder.highlightItem(selector);
dlayer.preview.changed = true;
} else {
if (optional == false) {
$(selector).attr(field_attribute, value);
$('#params-' + attribute).val(value);
} else {
$(selector).attr(field_attribute, '');
$('#params-' + attribute).val('');
previewFormBuilder.highlightItem(selector);
previewFormBuilder.changed = true;
}
}
previewFormBuilder.unsaved();
});
},
}
</code></pre>
<h3>Database</h3>
<p>Any contributions which require a change to the structure or content of the database should include
two patch files, one to make the required changes and another to undo the changes if anything goes
wrong.</p>
<p>If you are only making minor content updates, I will accept one patch file, an undo patch file
isn't necessary but very much appreciated if included.</p>
<p>If you review the commits, you will discover very quickly spot I am not following the guidelines for
Database changes; I will adhere to them once I have the set-up/reset scripts in place.</p>
</div>
</div>
</div>
<div class="footer">
<div class="container">
<div class="row">
<div class="col-lg-12 text-center text-muted">
<hr />
<p>Dlayer originally developed by
<a href="http://www.g3d-development.com/blog/">G3D
Development Limited</a> /
<a href="http://www.deanblackborough.com">Dean
Blackborough</a><br>
Dlayer Copyright © G3D Development 2017<br>
Maintained by <a href="http://www.deanblackborough.com/">Dean Blackborough</a>,
Code <a href="https://github.com/Dlayer/dlayer/blob/master/LICENSE">licensed</a> under MIT</p>
</div>
</div>
</div>
</div>
</body>
</html>