Updates to the coding standards manual

Hutchy68 · Hutchy68 · commit bbeb50ca8a18 · 2013-12-21T00:22:06.000-05:00
diff --git a/assets/css/manual.css b/assets/css/manual.css
@@ -13,4 +13,47 @@ th
 {
 	border: 1px solid gray;
 	padding: 10px;
+}
+.manual-image {
+	margin: .5em 0 2em 0;
+	text-align: center;
+}
+h1,h2,h3 {
+	line-height:36px;
+}
+h1 {
+	font-size:34.5px;
+}
+h2 {
+	font-size:28.5px;
+}
+h3 {
+	font-size:22.5px;
+}
+h4 {
+	font-size:18.5px;
+}
+h5 {
+	font-size:14px;
+}
+h6 {
+	font-size:11.9px;
+}
+h1 small {
+	font-size:22.5px;
+}
+h2 small {
+	font-size:18.5px;
+}
+h3 small {
+	font-size:14px;
+}
+h4 small {
+	font-size:14px;
+}
+#version {
+	float:right;
+	font-size:.85em;
+	font-weight:bold;
+}
 }
diff --git a/assets/js/manual.js b/assets/js/manual.js
@@ -52,6 +52,16 @@ var populateMenu = function() {
 	}).send();
 }
 
+var populateVersion = function() {
+	var versionRequest = new Request({
+		"url": here + 'manual/en-US/version.md',
+		"method": "get",
+		"onSuccess": function(response) {
+			$('version').set('html', marked(response));
+		}
+	}).send();
+}
+
 window.addEvent('domready', function() {
 	var urlParts = document.URL.split('?', 2);
 	state = {};
@@ -63,7 +73,7 @@ window.addEvent('domready', function() {
 	}
 	else
 	{
-		var currentDoc = "chapters/introduction.md";
+		var currentDoc = "coding-standards/introduction.md";
 	}
 
 	marked.setOptions({
@@ -78,6 +88,7 @@ window.addEvent('domready', function() {
 	})
 	populateMenu();
 	populateWindow(currentDoc);
+	populateVersion();
 
 	document.id('main').addEvent('click:relay(a)', function (event, target) {
 		if (target.get('href').substring(0, 4) != 'http' && target.get('href').substring(0, 1) != '#')
diff --git a/index.html b/index.html
@@ -33,18 +33,21 @@
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
           </a>
-          <a class="brand" href="#">Joomla! Coding Standards Manual</a>
+          <a class="brand" href="/coding-standards/">Joomla! Coding Standards Manual</a>
         </div>
       </div>
     </div>
 
     <div id="main" class="container-fluid">
       <div class="row-fluid">
         <div class="span3">
+          <div class="manual-image">
+          <img src="https://github.com/Hutchy68/coding-standards/blob/gh-pages/manual/en-US/coding-standards/joomla_coding_standards_manual.png?raw=true" alt="Joomla! Graphic">
+          </div>	
           <div class="well sidebar-nav" id="doc-menu">
           </div><!--/.well -->
         </div><!--/span-->
-        <div class="span9">
+        <div class="span9">	
           <div id="docwin">
           </div>
         </div><!--/span-->
@@ -53,13 +56,17 @@
       <hr>
 
       <footer>
+      	<div class="well">
+      	<h4>License</h4>
         <p>The contents of the Joomla! Coding Standards Manual are subject to copyright law and are made available under the <a href="http://docs.joomla.org/JEDL"
         title="Joomla! Electronic Documentation License (JEDL)">Joomla! Electronic Documentation License (JEDL)</a> unless otherwise stated.
         You may find the <a href="http://docs.joomla.org/JEDL/FAQ" title="JEDL Frequently Asked Questions">JEDL Frequently Asked Questions</a>
         useful in determining if your proposed use of this material is allowed. If you have any questions regarding licensing of this
         material please contact <a href="mailto:legal@opensourcematters.org" title="Email Open Source Matters">legal@opensourcematters.org</a>.
         If you wish to report a possible violation of the license terms for the material on this site then please contact
         <a href="mailto:legal@opensourcematters.org" title="Email Open Source Matters">legal@opensourcematters.org</a>.</p>
+        </div>
+        <div id="version"></div>      
       </footer>
 
     </div><!--/.fluid-container-->
diff --git a/manual/en-US/appendices/analysis.md b/manual/en-US/appendices/analysis.md
@@ -1,21 +1,18 @@
-### 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
+
+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 Platform 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.
 
-##### Running CodeSniffer
-
 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`
@@ -24,10 +21,17 @@ 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`
 
-##### Known Issues
+#### 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
@@ -0,0 +1 @@
+## Code Examples
diff --git 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
@@ -0,0 +1,3 @@
+## DocBlocks
+
+@TODO - Entend information about DocBlocks specific to the Framework and CMS. Other project?
diff --git a/manual/en-US/coding-standards/chapters/inline-comments.md b/manual/en-US/coding-standards/chapters/inline-comments.md
@@ -1,14 +1,14 @@
-## 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.
 
 Comments should be as sentence like as possible, which is to say that they should be complete and readable, not in short hand.
 
 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
@@ -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
@@ -1,16 +1,16 @@
 ## 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
 
 You can learn about how to get the Joomla Framework source code from the Git repository, https://github.com/joomla/joomla-framework.
 
 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
@@ -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).
diff --git a/manual/en-US/coding-standards/joomla_coding_standards_manual.png b/manual/en-US/coding-standards/joomla_coding_standards_manual.png
diff --git a/manual/en-US/coding-standards/preface.md b/manual/en-US/coding-standards/preface.md
diff --git 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)	
diff --git a/manual/en-US/version.md b/manual/en-US/version.md
@@ -0,0 +1 @@
+Version 1.0

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+## DocBlocks`
	`2`	`+`
	`3`	`+@TODO - Entend information about DocBlocks specific to the Framework and CMS. Other project?`