mirror of
https://github.com/WhatCD/Gazelle.git
synced 2024-12-13 10:56:26 +00:00
265 lines
6.7 KiB
Plaintext
265 lines
6.7 KiB
Plaintext
This document contains the coding standards for Gazelle.
|
|
This document is a work-in-progress and is subject to change.
|
|
|
|
NOTE: The standards defined in this document will likely differ from
|
|
what is actually seen in the Gazelle code. This document is the first
|
|
step in properly enforcing coding standards throughout the project.
|
|
|
|
|
|
== TABLE OF CONTENTS ==
|
|
|
|
1. FILE FORMATTING
|
|
2. CODE STYLING
|
|
2.1 Code styling for PHP and JavaScript
|
|
2.2 Code styling for CSS
|
|
2.3 Code styling for SQL
|
|
3. NAMING CONVENTIONS
|
|
3.1 Function names
|
|
3.2 Variable names
|
|
3.3 Class names
|
|
3.4 SQL names
|
|
3.5 Miscellaneous names
|
|
4. COMMENTS
|
|
5. USER INTERFACE
|
|
6. EXAMPLES
|
|
6.1 PHP examples
|
|
6.2 CSS examples
|
|
6.3 SQL examples
|
|
|
|
|
|
1. FILE FORMATTING
|
|
|
|
Tabs shall always be used for indentation.
|
|
|
|
Files shall be encoded in ASCII.
|
|
|
|
Files shall always use Unix-style line endings (LF). The program dos2unix
|
|
will take care of this for you if you have files that use Windows-style
|
|
line endings (CR+LF) or old Mac-style line endings (CR).
|
|
|
|
File names for PHP, CSS, and JavaScript files shall be all lowercase and
|
|
use underscores instead of spaces.
|
|
|
|
|
|
2. CODE STYLING
|
|
|
|
2.1 Code styling for PHP and JavaScript
|
|
|
|
All statement blocks, including functions, shall have the opening brace
|
|
at the end of the same line with a space before the brace. The astute
|
|
reader will note that this is K&R style with the exception of functions.
|
|
|
|
There shall be a space between a control structure statement (e.g. if,
|
|
elseif, for) and the following parenthesis.
|
|
|
|
There shall be a space around conditional operators.
|
|
|
|
When using ternary operators, spaces shall be used around the operators.
|
|
|
|
For conditional blocks, "elseif" is to be used instead of "else if".
|
|
|
|
In loops and conditional blocks, there shall be braces even if there is
|
|
only one statement.
|
|
|
|
In loops and conditional blocks, the statement(s) shall be placed on the
|
|
following lines.
|
|
|
|
When opening a PHP statement, "<?" shall be used instead of "<?php".
|
|
|
|
Switch cases in index files shall not contain substantial code. The use
|
|
of include statements is acceptable.
|
|
|
|
When building strings in PHP, single quotes shall be used when not
|
|
printing a variable.
|
|
|
|
When declaring JavaScript variables, "var" shall always be used.
|
|
|
|
2.2 Code styling for CSS
|
|
|
|
"property: value;" pairs shall be separated by a space, and the value
|
|
shall be followed by a semi-colon.
|
|
|
|
Multiple, related CSS selectors with the same declarations shall appear
|
|
on multiple lines to improve readability.
|
|
|
|
The opening brace shall be on the same line as the last related
|
|
selector with a space between the selector and the brace.
|
|
|
|
2.3 Code styling for SQL
|
|
|
|
Long SQL queries shall be separated on multiple lines.
|
|
|
|
Short SQL queries may be on a single line.
|
|
|
|
The primary SQL keywords should be at the same indentation level unless
|
|
part of a JOIN or other complex statement.
|
|
|
|
Use indents as appropriate to aid readability.
|
|
|
|
The SQL keywords JOIN, RIGHT JOIN, LEFT JOIN must be indented once from
|
|
the SELECT statement.
|
|
|
|
The SQL keyword AND must be indented once from the WHILE (and similar)
|
|
statements.
|
|
|
|
The "not equal to" operator "!=" must be used instead of the alternative
|
|
operator "<>".
|
|
|
|
|
|
3. NAMING CONVENTIONS
|
|
|
|
Function, variable, and class names shall always be descriptive.
|
|
|
|
3.1 Function names
|
|
|
|
PHP function names shall be written in lowercase_with_underscores.
|
|
|
|
JavaScript function names shall be written in camelCase with a leading
|
|
lowercase letter.
|
|
|
|
3.2 Variable names
|
|
|
|
PHP variable names shall be written in CamelCase with a leading
|
|
uppercase letter.
|
|
|
|
JavaScript global-scope variables shall be written in camelCase with a
|
|
leading lowercase letter.
|
|
|
|
JavaScript local-scope variables shall be written in
|
|
lowercase_with_underscores.
|
|
|
|
3.3 Class names
|
|
|
|
PHP class names shall be written in CamelCase with a leading uppercase
|
|
letter.
|
|
|
|
PHP class constants shall be written in CamelCase with a leading
|
|
uppercase letter.
|
|
|
|
3.4 SQL names
|
|
|
|
All SQL keywords shall be written in all UPPERCASE.
|
|
|
|
All SQL table names shall be written in lowercase_with_underscores.
|
|
|
|
All SQL column names shall be written in CamelCase with a leading
|
|
uppercase letter.
|
|
|
|
All automatically-incremented ID columns shall be named "ID", while the
|
|
other columns for ID numbers shall have names like RequestID, TorrentID,
|
|
etc.
|
|
|
|
3.5 Miscellaneous names
|
|
|
|
PHP global constants shall be written in ALL_CAPS.
|
|
|
|
PHP constants true, false, and null shall be written in all lowercase.
|
|
|
|
|
|
4. COMMENTS
|
|
|
|
Use C89-style "/* ... */" comments for multi-line comments.
|
|
|
|
Use C99-style "// ..." comments for single-line comments.
|
|
|
|
|
|
5. USER INTERFACE
|
|
|
|
All button labels shall use sentence case.
|
|
|
|
All table headings shall use sentence case.
|
|
|
|
All text-based buttons shall use the "brackets" CSS class.
|
|
|
|
Use common sense for design-related code. Microsoft's UI design guidelines
|
|
explain when certain form input controls should be used over others to
|
|
provide a familiar and intuitive interface. Refer to the following links
|
|
for the most likely issues to encounter in web design:
|
|
http://msdn.microsoft.com/en-us/library/windows/desktop/aa511452.aspx
|
|
http://msdn.microsoft.com/en-us/library/windows/desktop/aa511453.aspx
|
|
http://msdn.microsoft.com/en-us/library/windows/desktop/aa511488.aspx
|
|
http://msdn.microsoft.com/en-us/library/windows/desktop/aa511494.aspx
|
|
|
|
|
|
6. EXAMPLES
|
|
|
|
6.1 PHP examples
|
|
|
|
if ($Foo >= 0) {
|
|
$SomeString = "this is a string $DiffString with more text";
|
|
} elseif ($Foo == 0) {
|
|
// other things happen
|
|
} else {
|
|
// more magic
|
|
}
|
|
|
|
function works_magic($Foo, $Bar) {
|
|
return $Foo;
|
|
}
|
|
|
|
echo ($Foo == true ? 'foo is true' : 'foo is false');
|
|
|
|
if ($Foo == true) {
|
|
// magic happens
|
|
}
|
|
|
|
/*
|
|
* This is a good, multi-line comment.
|
|
*
|
|
* Please comment your code!
|
|
*/
|
|
|
|
// This is a good, single-line comment.
|
|
|
|
|
|
6.2 CSS examples
|
|
|
|
<a href="foobar.php" style="font-weight: bold;">link text</a>
|
|
|
|
.spellcheck {
|
|
margin: 10px 0;
|
|
font-size: 1.25em;
|
|
font-weight: bold;
|
|
}
|
|
|
|
.linkbox .brackets:before,
|
|
.linkbox .brackets:after,
|
|
.top10_quantity_links .brackets:before,
|
|
.top10_quantity_links .brackets:after {
|
|
color: #757575;
|
|
}
|
|
|
|
|
|
6.3 SQL examples
|
|
|
|
SELECT
|
|
r.ID, e.EditionID, r.Title, r.Year, r.CatalogueNumber,
|
|
l.Name AS Label, r.LabelID, r.Image, r.MusicBrainzID
|
|
FROM releases AS r
|
|
JOIN editions AS e ON e.ReleaseID = r.ID
|
|
LEFT JOIN labels AS l ON l.ID = r.LabelID
|
|
WHERE r.ID IN ($ReleaseIDsSQL)
|
|
ORDER BY e.EditionID, r.Year ASC
|
|
|
|
|
|
SELECT SQL_CALC_FOUND_ROWS c.ID, c.Subject, cu.Unread, cu.Sticky,
|
|
cu.ForwardedTo, cu2.UserID, cu.ReceivedDate AS Date
|
|
FROM pm_conversations AS c
|
|
LEFT JOIN pm_conversations_users AS cu ON cu.ConvID = c.ID
|
|
AND cu.UserID = '1'
|
|
LEFT JOIN pm_conversations_users AS cu2 ON cu2.ConvID = c.ID
|
|
AND cu2.UserID != '1'
|
|
AND cu2.ForwardedTo = 0
|
|
LEFT JOIN users_main AS um ON um.ID = cu2.UserID
|
|
WHERE um.Username LIKE 'test'
|
|
AND cu.InInbox = '1'
|
|
GROUP BY c.ID
|
|
ORDER BY cu.Sticky, Date DESC
|
|
LIMIT 25
|
|
|
|
|
|
SELECT RequestID AS ID, UserID FROM bookmarks_requests
|
|
|
|
|
|
EOF
|