mirror of
https://github.com/WhatCD/Gazelle.git
synced 2024-12-13 02:46:30 +00:00
299 lines
7.9 KiB
Plaintext
299 lines
7.9 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
|
|
1. Code styling for PHP and JavaScript
|
|
2. Code styling for CSS
|
|
3. Code styling for SQL
|
|
3. NAMING CONVENTIONS
|
|
1. Function names
|
|
2. Variable names
|
|
3. Class names
|
|
4. SQL names
|
|
5. Miscellaneous names
|
|
4. COMMENTS
|
|
5. USER INTERFACE
|
|
6. EXAMPLES
|
|
1. PHP examples
|
|
2. CSS examples
|
|
3. SQL examples
|
|
|
|
|
|
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
|
|
|
|
|
|
# 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.
|
|
|
|
|
|
# CODE STYLING
|
|
|
|
## 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 the opening
|
|
brace in function definitions.
|
|
|
|
There shall be a space between a control structure statement (e.g. `if`,
|
|
`elseif` in PHP, `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 PHP 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`. In
|
|
other words, use PHP's short tags.
|
|
|
|
Switch cases in index files shall not contain substantial code. The use
|
|
of include statements is acceptable.
|
|
|
|
When declaring JavaScript variables, `var` shall always be used.
|
|
|
|
When manually type casting, whitespace should not be used between the
|
|
cast operator and the variable.
|
|
|
|
## 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.
|
|
|
|
## Code styling for SQL
|
|
|
|
Long SQL queries shall be separated on multiple lines.
|
|
|
|
Short SQL queries may be on a single line.
|
|
|
|
All SQL keywords shall be uppercase.
|
|
|
|
Aliases shall be used to refer to any columns whenever multiple tables are
|
|
joined in an SQL query. They shall be using the `tbl_name AS alias_name`
|
|
syntax. No table aliases shall be used for single-table queries.
|
|
|
|
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 `WHERE` (and similar)
|
|
statements.
|
|
|
|
The "not equal to" operator `!=` must be used instead of the alternative
|
|
operator `<>`.
|
|
|
|
|
|
# NAMING CONVENTIONS
|
|
|
|
Function, variable, and class names shall always be descriptive.
|
|
|
|
## 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.
|
|
|
|
## 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`.
|
|
|
|
## 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.
|
|
|
|
## 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 Identification numbers shall have names like `RequestID`, `TorrentID`,
|
|
etc.
|
|
|
|
## Miscellaneous names
|
|
|
|
PHP global constants shall be written in `ALL_CAPS`.
|
|
|
|
PHP constants `true`, `false`, and `null` shall be written in all lowercase.
|
|
|
|
|
|
# COMMENTS
|
|
|
|
Use C89-style `/* ... */` comments for multi-line comments.
|
|
|
|
Use C99-style `// ...` comments for single-line comments.
|
|
|
|
|
|
# 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
|
|
|
|
|
|
# EXAMPLES
|
|
|
|
## 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.
|
|
|
|
|
|
## 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;
|
|
}
|
|
|
|
|
|
# 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
|