+
+
+
-
diff --git a/manual/en-US/appendices/analysis.md b/manual/en-US/appendices/analysis.md
index c6522aca..a534f7da 100644
--- a/manual/en-US/appendices/analysis.md
+++ b/manual/en-US/appendices/analysis.md
@@ -1,33 +1,37 @@
-### Configuring Code Analysis Tools
+## Coding Standards Analysis
-#### 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.
-In order to improve the consistency and readability of the source code,
-we run a coding style analysis tool everytime changes are pushed in the
-repo. 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
-The Joomla Platform sniffer rules are written to be used with a tool
-called PHP\_CodeSniffer. Please see the [PHP\_CodeSniffer Pear
+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.
+
+### Running 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.
+installing PHP CodeSniffer on your system.
-##### Running CodeSniffer
+You can run the CodeSniffer by going to the CMS, Framework, or Issue Tracker's root directory and executing
-You can run the CodeSniffer by going to the platform root directory and
-executing `phpcs --report=checkstyle
- --report-file=build/logs/checkstyle.xml --standard=/path/to/platform/build/phpcs/Joomla /path/to/platform`
+```
+phpcs --report=checkstyle --report-file=build/logs/checkstyle.xml --standard=/path/to/
/build/phpcs/Joomla /path/to/
+```
-Alternatively, if you have Ant installed on your system, you may run the
-CodeSniffer by going to the platform root directory and executing
-`ant phpcs`
+Alternatively, if you have Ant installed on your system, you may run the CodeSniffer by going to the `` of the Joomla project's code you want to test and executing
-##### Known Issues
+```
+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
+
+Here are some other tools available to developers who are planning to submit source code to the project.
+### PhpStorm Code Style Scheme
diff --git a/manual/en-US/appendices/examples.md b/manual/en-US/appendices/examples.md
new file mode 100644
index 00000000..7fda47f1
--- /dev/null
+++ b/manual/en-US/appendices/examples.md
@@ -0,0 +1 @@
+## Code Examples
\ No newline at end of file
diff --git a/manual/en-US/coding-standards/chapters/basic-guidelines.md b/manual/en-US/coding-standards/chapters/basic-guidelines.md
index fe984503..effbfe3d 100644
--- a/manual/en-US/coding-standards/chapters/basic-guidelines.md
+++ b/manual/en-US/coding-standards/chapters/basic-guidelines.md
@@ -1,20 +1,28 @@
## Basic Guidelines
-This chapter outlines the basic guidelines that cover and files.
+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
+### File Format
-All files contributed to Joomla must be stored as ASCII text, use UTF-8 character encoding and be Unix formatted. Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
+All files contributed to Joomla must be:
-## Spelling
+* Stored as ASCII text
+* Use UTF-8 character encoding
+* Be Unix formatted following these rules.
+ 1. Lines must end only with a line feed (LF).
+ 2. Line feeds are represented as ordinal 10, octal 012 and hex 0A.
+ 3. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
-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). However, 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.
+### Spelling
-## Indenting
+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
Tabs are used for indenting code (not spaces as required by the PEAR standard). Source code editors or Integrated Development Environments (IDE’s) such as Eclipse must have the tab-stops for indenting measuring four (4) spaces in length.
-## Line Length
+### 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).
diff --git a/manual/en-US/coding-standards/chapters/docblocks.md b/manual/en-US/coding-standards/chapters/docblocks.md
new file mode 100644
index 00000000..83823efd
--- /dev/null
+++ b/manual/en-US/coding-standards/chapters/docblocks.md
@@ -0,0 +1,3 @@
+## DocBlocks
+
+@TODO - Entend information about DocBlocks specific to the Framework and CMS. Other project?
\ No newline at end of file
diff --git a/manual/en-US/coding-standards/chapters/comments.md b/manual/en-US/coding-standards/chapters/inline-comments.md
similarity index 82%
rename from manual/en-US/coding-standards/chapters/comments.md
rename to manual/en-US/coding-standards/chapters/inline-comments.md
index 959e734a..7d090791 100644
--- a/manual/en-US/coding-standards/chapters/comments.md
+++ b/manual/en-US/coding-standards/chapters/inline-comments.md
@@ -1,6 +1,6 @@
-## Comments
+## Inline Code Comments
-This chapter covers inline commenting in more detail. Inline comments are all comments not included in doc blocs. The goal of in line commenting is to explain code in context. Such explanation may take many different forms.
+This chapter covers inline code commenting in more detail. Inline comments are all comments not included in doc blocs. The goal of in line commenting is to explain code in context. Such explanation may take many different forms.
Comments that are written in a readable and narrative style, especially when explaining a complex process, are encouraged. In general they should be placed close to the code explained rather than before the entire block of code.
@@ -8,7 +8,7 @@ Comments should be as sentence like as possible, which is to say that they shoul
Comments are not a replacement for detailed doc blocks. Comments serve to explain the logic and structure of code itself rather than the use of code.
-## Formatting of Comments
+### Formatting of Comments
Comment blocks that introduce large sections of code and are more than 2 lines long should use `/* */` (C) style and should use `*` on each line with the same space/tab rules as doc blocks. If you need a large introduction consider whether this block should be separated into a method to reduce complexity and therefore providing a full docblock.
@@ -22,7 +22,7 @@ Comments should align with the code they refer to, using the same indenting as t
Comments should be indented with tabs (like code, not like doc blocks).
-## Content of comments
+### Content of comments
Comments should use en-GB (See below).
@@ -46,23 +46,23 @@ Comments may include forward looking statements of how something will be extende
Remember that humor and sarcasm are difficult to translate.
-## Acronyms
+### Acronyms
Capitalise all letters of acronyms such as HTML, XML, SQL, GMT, and UTC. This is an exception to the general use of en-GB rules.
-## Common spelling and grammar errors for which to check.
+### Common spelling and grammar errors for which to check.
Joomla contributors include many non-native speakers of en-GB which makes it understandable that there are sometimes spelling and grammar errors. At the same time, some people reading comments also are non native speakers and may even use automated translation to understand comments. This makes it very important that comments should follow proper en-GB spelling and grammar rules. Unfortunately, these can be tricky.
-Wikipedia provides a good summary of common differences between en-US and en-GB. http://en.wikipedia.org/wiki/American\_and\_British\_English\_spelling\_differences Note that there are some instances where en-GB common usage (but not actual rules) varies slightly from en-AU and using en-AU is considered acceptable.
+Wikipedia provides a good summary of [common differences between en-US and en-GB](http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences). Note that there are some instances where en-GB common usage (but not actual rules) varies slightly from en-AU and using en-AU is considered acceptable.
-### S vs Z
+#### S vs Z
en-GB most commonly uses `ise` where en-US would use `ize`, such as `normalise` instead of `normalize`. (Note that there are some exceptions to this rule and some differences between en-GB and en-AU in common usage.)
Use of apostrophes is one of the trickier parts of English.
-### Lets versus let’s
+#### Lets versus let’s
Lets means permits or allows to:
@@ -76,7 +76,7 @@ Let’s is a contraction for let us and means we are going to do this now:
// Let's validate the field
```
-### Its versus it’s
+#### Its versus it’s
Its is the possessive form of it:
@@ -90,8 +90,8 @@ It’s is a contraction of it is
// It's time to save
```
-### The correct Joomla spelling of some commonly used words.
-
-- Dependant
+#### The correct Joomla spelling of some commonly used words.
+- dependant
+- deprecated
diff --git a/manual/en-US/coding-standards/chapters/php.md b/manual/en-US/coding-standards/chapters/php.md
index e0487609..89d53b3f 100644
--- a/manual/en-US/coding-standards/chapters/php.md
+++ b/manual/en-US/coding-standards/chapters/php.md
@@ -163,6 +163,8 @@ For example, do not include feature submissions like:
//$code = broken($fixme);
```
+More details on inline code comments can be found in the chapter on [Inline Code Comments](coding-standards/chapters/inline-comments.md).
+
### Comment Docblocks
Documentation headers for PHP and Javascript code in files, classes, class properties, methods and functions, called the docblocks, follow a convention similar to JavaDoc or phpDOC.
diff --git a/manual/en-US/coding-standards/chapters/source-code-management.md b/manual/en-US/coding-standards/chapters/source-code-management.md
index 4bab261b..7ee0a55c 100644
--- a/manual/en-US/coding-standards/chapters/source-code-management.md
+++ b/manual/en-US/coding-standards/chapters/source-code-management.md
@@ -1,8 +1,8 @@
## Source Code Management
-Before we start talking about what code should look like, it is appropriate to look at how and where the source code is stored. All serious software projects, whether driven by an Open Source community or developed within a company for proprietary purposes will manage the source code is some sort of source or version management system.
+Before we start talking about what Joomla! code should look like, it is appropriate to look at how and where the source code is stored. All serious software projects, whether driven by an Open Source community or developed within a company for proprietary purposes will manage the source code is some sort of source or version management system. The Joomla project uses a Distributed Version Control System (DVCS) called Git hosted at [GitHub.com](http://github.com).
-## The Joomla Framework
+### The Joomla Framework
The [Joomla Framework](https://github.com/joomla/joomla-framework) is a PHP framework that is designed to serve as a foundation for not only web applications (like a CMS) but other types of software such as command line applications. The files that form the Joomla Framework are stored in a Distributed Version Control System (DVCS) called Git hosted at github.com
@@ -10,7 +10,7 @@ You can learn about how to get the Joomla Framework source code from the Git rep
Because Git treats the concepts of file revision numbers differently than Subversion, the repository revision number is not required in files (that is, the `@version` tag is not necessary).
-## The Joomla CMS
+### The Joomla CMS
The [Joomla! CMS](https://github.com/joomla/joomla-cms) is a Content Management System (CMS) which enables you to build Web sites and powerful online applications. It's a free and OpenSource software, distributed under the GNU General Public License version 2 or later. The files that form the Joomla CMS are stored in a Distributed Version Control System (DVCS) called Git hosted at github.com
You can learn about how to get the Joomla CMS source code from the Git repository, https://github.com/joomla/joomla-cms.
diff --git a/manual/en-US/coding-standards/introduction.md b/manual/en-US/coding-standards/introduction.md
new file mode 100644
index 00000000..7c11c059
--- /dev/null
+++ b/manual/en-US/coding-standards/introduction.md
@@ -0,0 +1,19 @@
+## Introduction
+
+Good coding standards are important in any software development project. These standards are even more important when a large, diverse and worldwide community of developers are contributing to a project. One of the things that sets good software apart from great software is not only the features or the actual function the software performs, but the quality of its source code.
+
+In order to perform in the highly competitive Open Source and proprietary software industries, source code not only needs to be beautifully designed, it also needs to be beautiful and elegant to look at. The Joomla Coding Standards Manual is to help ensure our code is the highest quality which will make it easy to read, debug, and maintain.
+
+## Guiding Principles
+
+Since readable code is more maintainable, the compass that guides us in achieving that goal is a set of well thought out coding standards for the different software languages that are employed in the Joomla software project. Joomla has a solid heritage of striving to support a great looking product with great looking code.
+
+This manual compiles the collective wisdom of past and present contributors to the project to form the definitive standard for coding in Joomla, whether that is for the core Joomla Framework or an extension that forms part of the stack of the Joomla CMS. This manual also serves as a lighthouse to the Joomla developer community, to safely guide developers around the pitfalls of becoming lackadaisical with respect to writing clean, beautiful code.
+
+The Joomla Coding Standards borrows heavily from the PEAR coding standard for PHP files, augmenting and diverging where it is deemed sensible to do so.
+
+There are [tools available](appendices/analysis.md) to help your code conform to our standards.
+
+## Contributing to this manual
+
+If you want to contribute and improve this manual, you can find the source files at [https://github.com/joomla/coding-standards/tree/gh-pages](https://github.com/joomla/coding-standards/tree/gh-pages).
\ No newline at end of file
diff --git a/manual/en-US/coding-standards/preface.md b/manual/en-US/coding-standards/preface.md
deleted file mode 100644
index aeceb340..00000000
--- a/manual/en-US/coding-standards/preface.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Preface
-
-One of the things that sets good software apart from great software is not the features or the actual function the software performs, but the quality of the source code. In order to perform in the highly competitive Open Source and proprietary software industries, the source code not only needs to be beautifully designed, it also needs to be beautiful and elegant to look at.
-
-Readable code is maintainable code and the compass that guides us in achieving that goal is a set of well thought out coding standards for the different software languages that are employed in our software project. Joomla has a solid heritage of striving to support a great looking product with great looking code. This document compiles the collective wisdom of past and present contributors to the project to form the definitive standard for coding in Joomla, whether that is for the core Joomla Framework or an extension that forms part of the stack of the Joomla CMS. It also serves as a lighthouse to the Joomla developer community, to safely guide developers around the pitfalls of becoming lackadaisical with respect to writing clean, beautiful code.
-
-The Joomla Coding Standards borrows heavily from the PEAR coding standard for PHP files, augmenting and diverging where it is deemed sensible to do so.
diff --git a/manual/en-US/menu.md b/manual/en-US/menu.md
index cc39bedd..554523e1 100644
--- a/manual/en-US/menu.md
+++ b/manual/en-US/menu.md
@@ -1,9 +1,10 @@
-- Coding Standards
-- [Preface](coding-standards/preface.md)
+- [Introduction](coding-standards/introduction.md)
- [Source Code Management](coding-standards/chapters/source-code-management.md)
-- [Basic Guidelines](coding-standards/chapters/basic-guidelines.md)
-- [Comments](coding-standards/chapters/comments.md)
-- [PHP Code](coding-standards/chapters/php.md)
-
-- Appendices
-- [Code Analysis](appendices/analysis.md)
+- **Coding Standards**
+ - [Basic Guidelines](coding-standards/chapters/basic-guidelines.md)
+ - [Inline Code Comments](coding-standards/chapters/inline-comments.md)
+ - [DocBlocks](coding-standards/chapters/docblocks.md)
+ - [PHP Code](coding-standards/chapters/php.md)
+- **Appendices**
+ - [Code Analysis Tools](appendices/analysis.md)
+ - [Examples](appendices/examples.md)
\ No newline at end of file
diff --git a/manual/en-US/version.md b/manual/en-US/version.md
new file mode 100644
index 00000000..170de3a3
--- /dev/null
+++ b/manual/en-US/version.md
@@ -0,0 +1 @@
+Version 1.0
\ No newline at end of file