`
+- The document title does NOT need to be included in the document, these are displayed as the page heading based on the Joomla component configuration and would result in duplicated titles if included
+- Because the GitHub Markdown parser interprets line breaks as ` ` tags, arbitrary line breaks to keep lines from becoming too long should not be used
+- Links to documents in this manual should be formatted for use on the Joomla! Developer Network, such as `[a link to the Basic Guidelines page](/coding-standards/basic-guidelines.html)`
diff --git a/manual/appendices/analysis.md b/manual/appendices/analysis.md
index 6f36fe56..5391b360 100644
--- a/manual/appendices/analysis.md
+++ b/manual/appendices/analysis.md
@@ -1,16 +1,12 @@
-## Coding Standards Analysis
-
For new contributions we are going to be enforcing coding standards to ensure that the coding style in the source code is consistent. Ensuring that your code meets these standards will make the process of code contribution smoother.
-## Configuring Code Analysis Tools
+### Configuring Code Analysis Tools
-In order to improve the consistency and readability of the source code, the Joomla project runs a coding style analysis tool, CodeSniffer, everytime changes are pushed to a Joomla project's repository.
+In order to improve the consistency and readability of the source code, the Joomla project runs a coding style analysis tool, PHP_CodeSniffer, everytime changes are pushed to a Joomla project's repository.
-### Running CodeSniffer
+#### Running PHP_CodeSniffer
-The Joomla Coding Standards sniffer rules are written to be used with a tool called PHP CodeSniffer. Please see the [PHP CodeSniffer Pear
-Page](http://pear.php.net/package/PHP_CodeSniffer) for information on
-installing PHP CodeSniffer on your system.
+The Joomla Coding Standards sniffer rules are written to be used with a tool called PHP CodeSniffer. Please see the [PHP_CodeSniffer PEAR Page](http://pear.php.net/package/PHP_CodeSniffer) for information on installing PHP_CodeSniffer on your system.
You can run the CodeSniffer by going to the CMS, Framework, or Issue Tracker's root directory and executing
@@ -24,16 +20,10 @@ Alternatively, if you have Ant installed on your system, you may run the CodeSni
ant phpcs
```
-#### Known Issues
-
-- There is currently an issue with running the Code Sniffer on the
- Simplepie library. Pointing the sniffs at the libraries/joomla
- directory or below will avoid the issue.
-
-## Other Tools
+### Other Tools
Here are some other tools available to developers who are planning to submit source code to the project.
-### Set up the codesniffer
+#### Set up PHP_CodeSniffer
See in the documentation https://docs.joomla.org/Joomla_CodeSniffer#3._IDE_Integration
diff --git a/manual/appendices/examples.md b/manual/appendices/examples.md
index 7fda47f1..dfd54129 100644
--- a/manual/appendices/examples.md
+++ b/manual/appendices/examples.md
@@ -1 +1 @@
-## Code Examples
\ No newline at end of file
+Please contribute to this documentation page.
diff --git a/manual/basic-guidelines.md b/manual/basic-guidelines.md
index effbfe3d..c892129d 100644
--- a/manual/basic-guidelines.md
+++ b/manual/basic-guidelines.md
@@ -1,12 +1,11 @@
-## Basic Guidelines
-
This chapter outlines the basic guidelines covering files contributed to the Joomla project. The most important rule to remember when coding for the Joomla project, **if in doubt, please ask**.
### File Format
All files contributed to Joomla must be:
-* Stored as ASCII text
+* Stored as ASCII text
+ Exceptions: languages locales and some test files containing non-ASCII characters
* Use UTF-8 character encoding
* Be Unix formatted following these rules.
1. Lines must end only with a line feed (LF).
@@ -15,8 +14,7 @@ All files contributed to Joomla must be:
### Spelling
-The spelling of words and terms used in code comments and in the naming of class, functions, variables and constant should generally be in accordance with British English rules (en\_GB).
-Some exceptions are permitted, for example where common programming names are used that align with the PHP API or other established conventions such as for `color` where is it common practice to maintain US English spelling.
+The spelling of words and terms used in code comments and in the naming of class, functions, variables and constant should generally be in accordance with British English rules (en\_GB). Some exceptions are permitted, for example where common programming names are used that align with the PHP API or other established conventions such as for `color` where is it common practice to maintain US English spelling.
### Indenting
@@ -25,7 +23,3 @@ Tabs are used for indenting code (not spaces as required by the PEAR standard).
### Line Length
There is no maximum limit for line lengths in files, however, a notional value of about 150 characters is recommended to achieve a good level of readability without horizontal scrolling. Longer lines are permitted if the nature of the code for individual lines requires it and line breaks would have an adverse affect on the final output (such as for mixed PHP/HTML layout files).
-
-## Best Practices
-
-TODO Any words of wisdom about PHP best practice, maybe even references for design patterns? Can/should we link out to the JRD, Doc wiki and Developer site for additional resources?
diff --git a/manual/css.md b/manual/css.md
index 1a7f1963..befaa5f8 100644
--- a/manual/css.md
+++ b/manual/css.md
@@ -1,29 +1,30 @@
-## CSS
These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, namely:
1. [OOCSS Code Standards](https://github.com/stubbornella/oocss-code-standards)
2. [Oneweb Style Guide](https://github.com/nternetinspired/OneWeb/blob/master/STYLEGUIDE.md)
3. [Idiomatic CSS](https://github.com/necolas/idiomatic-css)
+### Commenting
-## Commenting
-
-### Major sections
+#### Major sections
Major code sections should be named in caps and within a full comment block, eg:
+
```css
/* ==========================================================================
PRIMARY NAVIGATION
========================================================================== */
```
-### Sub sections
+#### Sub sections
Subsections should be normally cased and within an open comment block.
+
```css
/* Mobile navigation
========================================================================== */
```
-### Verbose comments
+#### Verbose comments
+
```css
/**
* Short description using Doxygen-style comment format
@@ -43,22 +44,24 @@ Subsections should be normally cased and within an open comment block.
*/
```
-### Basic comments
+#### Basic comments
+
```css
/* Basic comment */
```
-### Uncompiled LESS/Scss comments
+#### Uncompiled LESS/Scss comments
+
```css
// These are stripped on compile.
```
-## CSS selectors
-Only use classes for CSS selectors, *never IDs* as they introduce unwanted specificity to the cascade. Using an ID as a css selector is like firing the first nuke; you begin a specifity war that can only escalate, with terrible consequence.
+### CSS selectors
+Only use classes for CSS selectors, *never IDs* as they introduce unwanted specificity to the cascade. Using an ID as a CSS selector is like firing the first nuke; you begin a specifity war that can only escalate, with terrible consequence.
To put it another way; Don't use a Sith Lord when just two Storm Troopers will suffice: [CSS Specificity Wars](http://www.stuffandnonsense.co.uk/archives/css_specificity_wars.html)
-### Class naming convention
+#### Class naming convention
Use dashes to create compound class names:
```css
@@ -75,7 +78,7 @@ Use dashes to create compound class names:
.compoundclassname {…}
```
-### Indentation
+#### Indentation
Rules should be indented one tab (equal to 4 spaces):
```css
@@ -89,7 +92,7 @@ Rules should be indented one tab (equal to 4 spaces):
.example {color: #000; visibility: hidden;}
```
-### Alignment
+#### Alignment
The opening brace must be on the same line as the last selector and preceded by a space. The closing brace must be on its own line after the last property and be indented to the same level as the opening brace.
```css
@@ -109,7 +112,7 @@ The opening brace must be on the same line as the last selector and preceded by
}
```
-### Property Format
+#### Property Format
Each property must be on its own line and indented one level. There should be no space before the colon and one space after. All properties must end with a semicolon.
```css
@@ -132,8 +135,9 @@ Each property must be on its own line and indented one level. There should be no
}
```
-### HEX values
+#### HEX values
HEX values must be declared in lowercase and shorthand:
+
```css
/* Good */
.example {
@@ -146,7 +150,7 @@ HEX values must be declared in lowercase and shorthand:
}
```
-### Attribute selectors
+#### Attribute selectors
Always use double quotes around attribute selectors.
```css
@@ -166,7 +170,7 @@ input[type='button'] {
}
```
-### Zero value units
+#### Zero value units
Zero values should not carry units.
```css
diff --git a/manual/docblocks.md b/manual/docblocks.md
index 1761479b..8661b05a 100644
--- a/manual/docblocks.md
+++ b/manual/docblocks.md
@@ -1,5 +1,3 @@
-## DocBlocks
-
Documentation headers for PHP code in: files, classes, class properties, methods and functions, called the docblocks, follow a convention similar to JavaDoc or phpDOC.
These "DocBlocks" borrow from the PEAR standard but have some variations specific for Joomla and the Joomla projects.
@@ -18,7 +16,7 @@ Short description (optional unless the file contains more than two classes or fu
* @category (optional and rarely used)
* @package (generally optional but required when files contain only procedural code. Always optional in namespaced code)
* @subpackage (optional)
-* @author (optional but only permitted in non-Joomla source files, for example, included third-party libraries like Geshi)
+* @author (optional but only permitted in non-Joomla source files)
* @copyright (required)
* @license (required and must be compatible with the Joomla license)
* @link (optional)
@@ -39,8 +37,7 @@ Example of a DocBlock Header:
```
### Class Definitions
-Class definitions start on a new line and the opening and closing braces are also placed on new lines. Class methods must follow the guidelines for Function Definitions. Properties and methods must follow OOP standards and be declared appropriately (using public, protected, private and static as applicable).
-Class definitions, properties and methods must each be provided with a DocBlock in accordance with the following sections.
+Class definitions start on a new line and the opening and closing braces are also placed on new lines. Class methods must follow the guidelines for Function Definitions. Properties and methods must follow OOP standards and be declared appropriately (using public, protected, private and static as applicable). Class definitions, properties and methods must each be provided with a DocBlock in accordance with the following sections.
#### Class DocBlock Headers
The class Docblock consists of the following required and optional elements in the fol-lowing order.
@@ -49,7 +46,7 @@ Short description (required, unless the file contains more than two classes or f
* @category (optional and rarely used)
* @package (optional)
* @subpackage (optional)
-* @author (optional but only permitted in non-Joomla source files, for example, included third-party libraries like Geshi)
+* @author (optional but only permitted in non-Joomla source files)
* @copyright (optional unless different from the file Docblock)
* @license (optional unless different from the file Docblock)
* @link (optional)
@@ -88,8 +85,6 @@ Example of Class property DocBlock:
protected static $userId = 0;
```
-
-
#### Class Method DocBlocks and Functions DocBlocks
Function definitions start on a new line and the opening and closing braces are also placed on new lines. An empty line should precede lines specifying the return value.
diff --git a/manual/html.md b/manual/html.md
index fbd4e78c..2278e023 100644
--- a/manual/html.md
+++ b/manual/html.md
@@ -1,14 +1,11 @@
-## html
-
These guidelines have been assembled following an examination of emerging practices, ideas and existing styleguides, and include items from:
-1. [Google's html styleguide](https://google.github.io/styleguide/htmlcssguide.html)
-2. [JQuery's HTML Styleguide](http://contribute.jquery.org/style-guide/html/)
+1. [Google's HTML styleguide](https://google.github.io/styleguide/htmlcssguide.html)
+2. [jQuery's HTML Styleguide](http://contribute.jquery.org/style-guide/html/)
3. [Nicolas Ghallager's "Principles of writing consistent, idiomatic HTML"](https://github.com/necolas/idiomatic-html)
4. [Harry Robert's "My HTML/CSS coding style"](http://csswizardry.com/2012/04/my-html-css-coding-style/)
4. [The BBC's Media Standards and Guidelines](http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml)
-
### Doctype
Always use the minimal, versionless doctype.
@@ -26,19 +23,17 @@ Always define which language the page is written in.
```
### Encoding
-Always define the character encoding. The encoding should be defined as early as possible.
-Make sure your editor uses UTF-8 as character encoding, without a byte order mark (UTF-8, no BOM).
-Do not specify the encoding of style sheets as these assume UTF-8.
+
+Always define the character encoding. The encoding should be defined as early as possible. Make sure your editor uses UTF-8 as character encoding, without a byte order mark (UTF-8, no BOM). Do not specify the encoding of style sheets as these assume UTF-8.
```html
```
-[More on encodings and when and how to specify them can be found in Handling character encodings in HTML and CSS](http://www.w3.org/International/tutorials/tutorial-char-enc/)
-
+More on encodings and when and how to specify them can be found in [Handling character encodings in HTML and CSS](http://www.w3.org/International/tutorials/tutorial-char-enc/)
### Capitalisation
-All html should be lowercase; element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings). Additionally, there is no need to use CDATA to escape inline JavaScript, formerly a requirement to meet XML strictness in XHTML.
+All HTML should be lowercase; element names, attributes, attribute values (unless text/CDATA), CSS selectors, properties, and property values (with the exception of strings). Additionally, there is no need to use CDATA to escape inline JavaScript, formerly a requirement to meet XML strictness in XHTML.
```html
@@ -76,10 +71,12 @@ This prevents mixed content issues and results in minor file size savings.
### Elements and Attributes
-Always include html, head, and body tags.
+Always include ``, ``, and `` tags.
### Type attributes
+
Do not use type or attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
+
```html
@@ -89,6 +86,7 @@ Do not use type or attributes for style sheets (unless not using CSS) and script
```
### Language attributes
+
Do not use language attributes on script tags.
```html
@@ -98,21 +96,24 @@ Do not use language attributes on script tags.
+
```
Use attribute/value pairs for boolean attributes
+
```html
+
```
@@ -127,6 +128,7 @@ HTML attributes should be listed in an order that reflects the fact that class n
```html
Text
+
Text
```
@@ -143,33 +145,38 @@ Elements with multiple attributes can have attributes arranged across multiple l
```
### Elements
+
Optional closing tags may not be omitted.
+
```html
The quick brown fox jumps over the lazy dog.
+
The quick brown fox jumps over the lazy dog.
```
Self-closing (void) elements should not be closed. Trailing forward slashes and spaces should be omitted.
+
```html
+
```
-
### Formatting
+
Use a new line for every block, list, or table element, and indent every such child element.
```html
-
-
Home
-
Blog
-
+
+
Home
+
Blog
+
@@ -205,17 +212,17 @@ Tip: configure your editor to "show invisibles". This will allow you to eliminat
Taxes
-
-
$ 5.00
-
$ 4.50
-
+
+
$ 5.00
+
$ 4.50
+
+
```
### Indentation
-Don't indent inside html, body, script, or style. Indent inside head and all other elements.
-Indent by four spaces at a time. Don’t use tabs or mix tabs and spaces for indentation.
+Don't indent inside ``, ``, `
+