This document defines formatting and style rules for HTML, CSS, SASS, JS and PHP in order to improve collaboration, code quality, and maintainability. It is important that the standards set forth in this document are closely followed and strictly enforced so that code quality is maintained. The ultimate goal is to have the code look like a single person wrote it, no matter how many contributors.
*Denotes standards that are less common.
All files must use Unix style line-endings \n must be commented while you are writing it. Do not go back after the fact to add explanatory comments because chances are you not only will neglect to do this, you will likely have to spend time figuring out your own code.
Write code for humans, not machines.
Other developers will eventually need to maintain and extend your code, so write your code with them in mind. Use whitespace, tabbing, and naming to be as expressive as possible, and suptliment comments only when necessary. Each line of whitespace or tab should communicate.
Avoid optimizing code for compression rather than readability. Since there are server-side processes that handle concatenation and compression, we should not concern ourselves too much with saving a few bytes here and there.
All template file names should be hyphen-cased. Use descriptive file names that read from general to specific. i.e.
// Incorrect. Css and js are more specific than header.
css-header.phtml
html-footer.phtml
html-header.phtml
js-header.phtml
// Correct!
footer-html.phtml
header-css.phtml
header-html.phtml
header-js.phtml
// Incorrect.
content-detail-product.phtml
detail-product-sidebar.phtml
list-product.phtml
list-services.phtml
// Correct!
product-detail-content.phtml
product-detail-sidebar.phtml
product-list.phtml
services-list.phtml
// Incorrect.
main-nav.phtml
secondary-nav.phtml
sidebar-nav.phtml
// Correct!
nav-main.phtml
nav-secondary.phtml
nav-sidebar.phtml
This not only clarifies file contents, but also helps organize your files by grouping similar files together. Your end file structure should follow the same logic and order as your sitemap.
|-- app // MVC - App logic
| |-- controllers // MVC - Controllers
| |-- helpers // MVC - Helpers functions for controllers
| |-- models // MVC - Models
| |-- views // MVC - Views
| |-- webroot // Exposed content to everyone (Assets)
| |-- css // CSS compiled files
| |-- fonts // Fonts used in the proyect
| |-- images // Proyect images
| |-- js // JS compiled files
| |-- plugins // Third-party JS script compound by many kind of files
|-- config // Config proyect files (db_settings, host)
|-- migrations // MVC - Migrations files (dumps, seeds, creations)
|-- ui-sources // All the ui contents
|-- |-- base-sass // All sass base files, like font an functions definitions
|-- |-- components // UI components, a folder which contains each component with its scss, js and test
|-- |-- lib // third party libraries
|-- vendors // PHP clases, snippets, etc. not owned by us
Spaces are preferred over tabs for indentation. Indentation size should be controlled by the preferences in the text editor of whoever is writing/editing the code. Each indentation should have 4 spaces.
Indent each child element one more indent than its parent. Use an empty line to indicate logical separations between sibling elements. Use a new line for every block, list, or table element, and indent every such child element.
Lines should ideally be less than 80 characters. In rare cases, longer lines are acceptable but should never exceed 120 characters.
All markup should be lowercase. When quoting attributes values, use double quotation marks. It is preferred that attributes be alphabetized for consistency, with CSS classes organized from from most specific to least specific, i.e. page specific classes before image replacement helper classes.
For HTML elements that have more than two attributes or opening tags that exceeds the ideal line length, each attribute should be broken out on a new line and indented a further level. It is preferred, that the closing > should be on the same line as the last attribute. If an element has attributes on individual lines, all children elements should be indented a tab further while the closing tag should share the same indentation level as the opening tag. i.e.
<a
class="add-member-button"
data-member_id="43"
href="/add/member"
id="add-member-button">
Create Account
</a>
All the <a> tags shlould have a href to accomodate accessibility and web crawlers. Also, <img> tags should have a src url. Changing image urls via Javascript for responsive design should be a progressive enhancement.
Use inline styles only where necessitated by integration. Place all <script> elements directly above the closing <body> tag with the exception of Modernizr, which must be placed directly above the closing <head> tag.
All markup should be as semantically valid and accurate as possible. Elements should be expressive and chosen based on content and purpose. Avoid div's unless the element is simply used for stylistic purposes. When in doubt, consult HTML5 Doctor specifically this fantastic flow chart.
It is preferred that a <ul> element be used inside a <nav> element.
Avoid empty tags where ever possible.
Valid, W3C Compliant markup must be used at all times, this includes using label, fieldset, and legend elements properly. If necessary, use a validator.
HTML5 document type and UTF-8 encoding should be used and type attributes for style sheets and scripts should be omitted.
For void elements, include a / character before the closing >.
Comments should be used to explain any atypical or complex markup.
Comment the closing tag of main elements that contain more than one child or more than one level of children. i.e. <!-- .class --> or <!-- #id -->
Any purely stylistic variations such as all-caps or all-lowercase should be handled by CSS properties like text-transform unless such a presentation is not possible in CSS like textInCamelCase. Note that this does not apply to elements like acronym and abbr, both of which can appropriately contain all-caps text.
Headings h1 - h6 are used to label sections of content or modules.
The h1 element is reserved for the main heading of the page such as an article title. Only include a single h1 per page. This is good for SEO and semantically appropriate as well.
Forms must be marked up in as accessible/platform-independent a manner as possible. Form elements must be contained inside a block-level element, preferably a list. All form controls must have an ID attribute that matches its name and a descriptive label, even if the label ends up hidden from sighted users.
When using radio buttons or checkboxes, the preferred pattern is to not use the for attribute and simply wrap the input inside the label. In this case, you can leave an ID off the input.
<label><input type="radio" name="x" value="y" /> Label Text</label>
If your form contains a file input, set the enctype="multipart/form-data" attribute on the form itself.
Every form must have an actual submit button.
It's important to use clear, thoughtful, and appropriate names for classes and id's. Both should read from general to specific. i.e. button-submit Use verbose, descriptive names.
Separate words in id's and class names by a hyphen; no underscores or camel case. This improves readability and scannability.
Styles should not be based on a specific hosting template or page id. This allows them to be re-usable within the site.
Spaces are preferred over tabs for indentation. Indentation size should be controlled by the preferences in the text editor of whoever is writing/editing the code. Each indentation should have 4 spaces.
Indent each child element one more indent than its parent. Use an empty line to indicate logical separations between sibling elements. Use a new line for every block, list, or table element, and indent every such child element.
By default, always start with one level of indentation. Use indentation to indicate HTML hierarchy. i.e. If a h2 is contained inside of div.class, the referenced h2 should be indented four spaces further than div.class in the stylesheet. This mirrors the formatting of nested elements in SASS.
Consistency in use of whitespace is important; whitespace improves readability.
Remove trailing whitespace at the end of lines.
Always put each declaration and each selector on a separate line, i.e.
h1,
h2,
h3 {
border: 1px solid #333;
color: #333;
}
Include a single space before the opening brace of a ruleset.
Include a single space after the colon of a declaration. No space before.
Include a semi-colon at the end of the last declaration in a declaration block.
Place the closing brace of a ruleset in the same column as the first character of the ruleset.
Separate each ruleset by a blank line.
All code with the exception of comments must be lowercase.
Use lowercase in Table of Contents.
Capitalize font names "Arial", "Georgia". Don't capitalize font families serif, sans-serif, monospace.
All properties should be placed in alphanumeric order (0-9 A-Z) ignoring browser-specific prefixes. If browser-specific prefixes are needed, the should be grouped in alphanumeric order but placed in overall order based on the CSS3 property name. i.e.
background: #fff;
border-radius: 5px;
-moz-border-radius: 5px;
-webkit-border-radius: 5px;
color: #333;
display: inline-block;
text-align: center;
width: 100%;
Use px for font-size and line-height. Where allowed, don't specify units for zero-values. i.e. margin: 0; or top: 0;
Pad all decimals. i.e. rgba(0, 0, 0, 0.5)
Use lowercase hex color codes and 3 character shorthand where applicable.
When using percentages based on complex calculations dictated by design, comment to clarify. i.e.
.individuals-families {
width: 32.377740304%; // 192px/593px
}
With SASS, avoid using overly specific selectors. Only nest selectors when necessary as to not produce inefficient CSS that is hard to overwrite.
Do not use CSS hacks for targeting legacy browsers. Instead use the class on the HTML tag to override default styles.
Each SASS file should include the file name on the first line. Denote major elements or sections with main level flags. The flag should be the selector prefixed by an underscore. Flags should be indented one less tab than the selector they reference.
// -----------------------------------------------------------------------------
// _#main-level
// -----------------------------------------------------------------------------
#main-level {}
Include as many sub level flags as necessary to break the file into logical sections.
// _.sub-level
// -----------------------------------------------------------------------------
.sub-level {}
All flags should be included in a table of contents at the top of the file. Use tabs to clarify hierarchy
// -----------------------------------------------------------------------------
// Table of Contents (keep up-to-date)
// -----------------------------------------------------------------------------
//
// _#main-level
// _.sub-level
//
// -----------------------------------------------------------------------------
All SASS files should be prefixed with an underscore and included in a single file so only one SASS file is compiled. Each file should be name _module-name.breakpoint.scss or _page-name.breakpoint.scss. Each module, page, or global should have a file for each breakpoint even if no styles are needed. The file structure should follow:
|-- uisources // Gloabl content but only will have the main styles.scss
|-- base-sass // The sass base files, like mixins definitions, breakpoints, etc.
|-- components // Each component will have its own scss file
File names should be lowercase with words separated by hyphens and should describe the file contents.
Functions and methods should be camelCased and read like well written prose. Functions that return a boolean should be interrogative. Functions that do something should begin with a verb. For example, a function that logs a user in could be named loginUser(), where as a function that checks if a user is logged in could be named isLoggedIn().
Constants should be all uppercase with an underscore separating words.
Variables should also be camelCased. Variables that store jQuery objects should be prefixed with a $. Loops are the only occasion where a one letter variable is acceptable. Unless you already have a specific counting variable, use i as the variable for the outermost loop, then increment alphabetically. Do not use l (lowercase 'L') as it looks too similar to the number 'one'. i.e.
for (var i = 0; i < 5; i++) {
for (var j = 0; j < 4; j++) {
for (var k = 0; k < 3; k++) {
for (var m = 0; m < 3; m++) {
doSomething(i, j, k, m);
}
}
}
}
Declare all variables using var before use to avoid implied globals. All assignments must end in a semicolon.
For indentation, all code should follow strict 1TBS.
Spaces are preferred over tabs for indentation. Indentation size should be controlled by the preferences in the text editor of whoever is writing/editing the code. Each indentation should have 4 spaces.
Indent each child element one more indent than its parent. Use an empty line to indicate logical separations between sibling elements. Use a new line for every block, list, or table element, and indent every such child element.
It is preferred that the values of object properties not be tabbed to align. i.e.
// Incorrect.
badObject = {
oneProperty: 'value',
anotherProperty: 'value'
}
// Correct.
goodObject = {
oneProperty: 'value',
anotherProperty: 'value'
}
Control statements include if, switch, while, for, etc. These statements should have a single space before the opening parenthesis of the expression and a single space after the closing parenthesis. Operators within the expression should always be padded with a space before and after the operator, except for commas and semicolons, which should just have a single space after the operator. i.e.
if (foo == bar) {
foo++;
}
if (! foo) {
foo = bar;
}
for (var i = 0; i < 10; i++) {
foo[i] = bar;
}
Lines should ideally be less than 80 characters. In rare cases, longer lines are acceptable but should never exceed 120 characters. Following the line length standard not only improves the code's readability, but also helps enforce good, clean code.
When concatenating strings or dealing with chained methods, break them into multiple lines for improved readability. Use indentation to convey hierarchy. i.e.
$thisSlide
.find(HEADER_NAV_SUB_PANE_CLASS)
.not('.' + HEADER_NAV_ACTIVE_CLASS)
.addClass(HEADER_NAV_ACTIVE_CLASS);
Use a blank line between logical breaks in your code. Multiple variable declarations should not have a blank line between them. Use a blank line before and after a control statement. Constants, variables, and cached objects should be grouped and separated by a blank line.
let variableName = 0;
let objectName = {};
const CONSTANT_NAME = 'selector';
doSomething();
if (variableName < 10) {
doSomethingElse();
} else {
doSomethingNothing();
}
return false;
Functions and methods should do one thing and one thing only. It's been suggested that functions and methods be no longer than four lines of code. That is ideal, but not always possible. Regardless, the number of lines in your methods and functions will be short if they only do one thing. The best way to tell if your function only does one thing is to abstract until you can not abstract any more.
Ternary operators are allowed only where logical and efficient. However, you should never have nested ternary operators. Ternary conditions should be wrapped in parenthesis for readability, even if it's just a single conditional. Ternary operators may also be broken up into multiple lines if it makes sense to do so. When broken into multiple lines, the "?" and ":" operators should line up and be indented one tab further. i.e.
a = (b == c && b == d)
? $thisNameIsReallyReallyRidiculouslyLong
: $notQuiteAsLong;
Accessing and altering the DOM is slow. Minimize DOM manipulation.
Cache objects in variables if they are used more than once.
// Incorrect.
document.querySelector('#element').classList.add('class');
document.querySelector('#element').doSomething('class');
callSomeFunction(document.querySelector('#element'));
// Correct.
const dom = document.querySelector('#element');
dom.addClass('something');
dom.doSomethingElse();
callSomeFunction(dom);
Any AJAX call should get the target url from an href attribute, form action, or appropriate data attribute.
All JS written should be clean and efficient and must pass JSHint.
Never use document.write(), eval, continue, or with. Also avoid passing strings to setTimeout and setInterval, which will causes them to use eval.
Use native event methods like event.preventDefault(); and event.stopPropagation(); to prevent default actions instead of return false;.
All methods and functions should be commented with a JSDoc comment. The block should at minimum contain the @return variable and a description, but may also contain one or multiple @param variables. Functions that do not return anything should be marked as @return {void}.
Comments should be used infrequently. Your code should be written in a way that is easy to understand, making comments unnecessary. Before adding a comment, make sure that expressive function names, variable substitution, or refactoring are not the proper approach. If you do have to leave a comment, the comment should be directly above the line of code that it addresses.
All animations, including hide and show, should be handled with classes and CSS3 transitions. Only in rare cases like parallax and one-to-one mouse or touch animaitons, is jQuery acceptable.
The -js should follow this structure.
|-- ui-sources // not any js file
| |-- components // every single component on its containing folder with js file and spec file
| |-- libs // third party libraries (like dumbojs)
For the file names see Models, Views, Controllers and Helpers.
Functions and methods should be camelCased and read like well written prose. Functions that return a boolean should be interrogative. Functions that do something should begin with a verb. For example, a function that logs a user in could be named loginUser(), where as a function that checks if a user is logged in could be named isLoggedIn().
Constants should be all uppercase with an underscore separating words.
Variables should also be camelCased. Loops are the only occasion where a one letter variable is acceptable. Unless you already have a specific counting variable, use $i as the variable for the outermost loop, then increment alphabetically. Do not use l (lowercase 'L') as it looks too similar to the number 'one'. i.e.
for($i = 0; $i < 5; $i++):
for($j = 0; $j < 4; $j++):
for($k = 0; $k < 3; $k++):
for($m = 0; $m < 3; $m++):
doSomething($i, $j, $k, $m);
endfor;
endfor;
endfor;
endfor;
For indentation, all code should follow strict 1TBS.
Spaces are preferred over tabs for indentation. Indentation size should be controlled by the preferences in the text editor of whoever is writing/editing the code. Each indentation should have 4 spaces.
Indent each child element one more indent than its parent. Use an empty line to indicate logical separations between sibling elements. Use a new line for every block, list, or table element, and indent every such child element.
It is preferred that the values of object properties not be tabbed to align. i.e.
// Incorrect.
$badArray = [
'oneProperty' => 'value',
'anotherProperty' => 'value'
]
// Correct.
$goodArray = [
'oneProperty' => 'value',
'anotherProperty' => 'value'
]
For Functions, Classes, Traits and Interfaces, the opening brace shoul be on same line as name. i.e.
function myFunction($param) {
//statements
}
Interface myInterface {
//statements
}
Trait myTrait {
//statements
}
Class myClass Extends anotherClass Implements myInterface {
use myTrait;
//statements
}
If your if() or loop only contains one executable statement, the containing braces are optional, and should be omitted. i.e.
if(expression)
//statement
// or
foreach($array as $key => $value)
// statement
Braces should not be used for blocks if, switch, while, for and foreach, Use the form block: endblock; i.e.
if($foo === $bar):
$foo++;
endif;
for($i = 0; $i < 10; $i++):
$foo[$i] = $bar;
endfor;
foreach($array as $index => $element):
foo[$index] = $element;
endforeach;
while($value !== 0):
$value--;
endwhile;
switch($value):
case 1:
//statement
break;
default:
//statement
break;
endswitch;
The statement should still be indented as usual, and kept on a separate line for readability.
It's best practice if code is sufficiently commented to aid future developers who may have to pick it up. At the very least, all functions and class methods should be commented in the DocBlock format, and should contain a brief description about that function, and details on the inputs and outputs. A decent IDE should be able to automatically supply a lot of these details for you when you open the DocBlock with /** and hit enter.
i.e.
/**
* return a filtered string
* @param string $filter_line the string to be filtered
* @param string $replace_char optional character to use as the replacement - defaults to *
* @return string
*/
public function filter_string($filter_line, $replace_char='*') {
...
Avoid this if you can. Most IDEs and advanced text editors have an option to automatically strip trailing whitespace upon saving of a file, and you should enable this option if it exists.
Lines should ideally be less than 80 characters. In rare cases, longer lines are acceptable but should never exceed 120 characters. Following the line length standard not only improves the code's readability, but also helps enforce good, clean code.
When concatenating strings or dealing with chained methods, break them into multiple lines for improved readability. Use indentation to convey hierarchy. i.e.
$object
->method1()
->returnedMethod2()
->returnedAttribute;
When concatenating, try to avoid it, use interpolation and Nowdoc instead.
Use a blank line between logical breaks in your code. Multiple variable declarations should not have a blank line between them. Use a blank line before and after a control statement. Constants and variables, should be grouped and separated by a blank line.
Class myClass Extends anotherClass Implements myInterface {
use myTrait;
public $property1;
public $property2;
public $property3;
private $privateProp1;
private $privateProp2;
private $privateProp3;
public function myFunction() {
//sentences
}
}
Functions and methods should do one thing and one thing only. It's been suggested that functions and methods be no longer than four lines of code. That is ideal, but not always possible. Regardless, the number of lines in your methods and functions will be short if they only do one thing. The best way to tell if your function only does one thing is to abstract until you can not abstract any more.
Ternary operators are allowed only where logical and efficient. However, you should never have nested ternary operators. Ternary conditions should be wrapped in parenthesis for readability, even if it's just a single conditional. Ternary operators may also be broken up into multiple lines if it makes sense to do so. When broken into multiple lines, the "?" and ":" operators should line up and be indented one tab further. i.e.
$a = ($b === $c and b === d)
? $thisNameIsReallyReallyRidiculouslyLong
: $notQuiteAsLong;
There is another choice in order to approach efficient logic: using non-void returned functions with condittional operatos:
empty($var) and print('Empty var');
// this is also correct
empty($var) and ($var = 1);
The models should contain logic as much as possible. Always will handle data-manipulation methods and event-based callbacks. i.e.
Class User extends ActiveRecord {
public $before_insert = array('encryptPassword');
public function encryptPassword() {
$this->password = md5($this->password);
}
}
Or, this way is acceptable too:
Class User extends ActiveRecord {
public function init() {
$this->before_insert = array('encryptPassword');
}
public function encryptPassword() {
$this->password = md5($this->password);
}
}
Any data-model manipulation on controllers is not allowed, unless extremly needed.
If is possible, avoid HTML output via echo or print unless you have prebuilded HTML; always use php script insertion. i.e.
<table>
<? foreach($this->users as $user): ?>
<tr>
<td><?=$user->name;?></td>
</tr>
<? endforeach; ?>
</table>
Use always short open tags and the simplified echo <?=$var;?>.
The file naming should use the Dumbo PHP Framework standards.
The controllers should handle logic for the navigation flow. The controllers folder will contain Traits and additional clases for use and inclusion into the controllers.
The file naming should use the Dumbo PHP Framework standards.
The helpers should only have functions for across controllers calls, like session handler.
The file naming should use the Dumbo PHP Framework standards.
The entire project should follow this structure.
|-- app // MVC - App logic
| |-- controllers // MVC - Controllers
| |-- helpers // MVC - Helpers functions for controllers
| |-- models // MVC - Models
| |-- views // MVC - Views
| |-- webroot // Exposed content to everyone (Assets)
| |-- css // CSS compiled files
| |-- fonts // Fonts used in the proyect
| |-- images // Proyect images
| |-- js // JS compiled files
| |-- plugins // Third-party JS script compound by many kind of files
|-- config // Config proyect files (db_settings, host)
|-- migrations // MVC - Migrations files (dumps, seeds, creations)
|-- vendors // PHP clases, snippets, etc. not owned by us
You should commit frequently and in logical increments. Commit messages should be clear and informative.
You should add the precommit hook with execution permissions into the git hooks, regarding to execute unit testing before the commit to ensure one only clear commit.
Code will not be considered complete until it meets all standards and matches design comps with acceptable pixel accuracy. This means that all pages are identical to the designs including color, font size, font weight, etc. The only exceptions are adjustments in mis-calculated spacing, non-pixel increments, and alignment with the grid. No JS containing console.log() or alert() will be considered complete.
I agree to maintain these standards over the duration of the project.
CMS-Propaganda-1.0
Javier Serrano