mirror of
https://github.com/WhatCD/Gazelle.git
synced 2024-12-14 19:36:25 +00:00
251 lines
6.1 KiB
Plaintext
251 lines
6.1 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. Do not use spaces to make code
|
|
blocks align in a pretty fashion.
|
|
|
|
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.
|
|
|
|
|
|
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 buttons shall use sentence case.
|
|
|
|
All table headings shall use sentence case.
|
|
|
|
All text-based buttons shall use the "brackets" CSS class
|
|
|
|
|
|
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
|