Skip to content

Coding Standards

Jump to bottom Edit New page
joanneci edited this page May 11, 2014 · 25 revisions
Table of Contents
# Overview Our Standards specify a common format for source code and comments. We put these in place to easily read, share and modify code and to ensure consistency in our applications. All developers working on our code base should ensure working functionality and adherence to Coding Standards prior to moving a job to Functional or Code Review. ## Project Architecture ### MVC approach

The Worklist project employs the Model/View/Controller Architecture. By definition, "MVC is a software architectural pattern for implementing user interfaces. It divides a given software application into three interconnected parts, so as to separate internal representations of information from the ways that information is presented to or accepted from the user".

  • A Controller can send commands to the model to update the model's state (e.g., editing a document). It can also send commands to its associated view to change the view's presentation of the model (e.g., by scrolling through a document).

  • A Model notifies its associated views and controllers when there has been a change in its state. This notification allows the views to produce updated output, and the controllers to change the available set of commands. In some cases an MVC implementation might instead be "passive," so that other components must poll the model for updates rather than being notified.

    Note: Most models in Worklist are still legacy code; almost all of them extend from DataObject. The future plan is to extend all models from the Model class, in the same way the Entry model is today.

  • A View requests information from the model that it needs for generating an output representation to the user.

    Note: In Worklist, views are split on an object representation and its markup:

    views
|-> Job.php, Project.php, [...]
|-> mustache
|   |-> jobs.mustache, project.mustache, [...]
|   \-> partials
|       \-> [...]
\-> layout
    |-> Default.php, NewWorklist.php, EmptyBody.php
    \-> mustache
        \-> default.mustache, newworklist.mustache, emptybody.mustache

    The class/object part takes care of collecting all the data the view is going to use; they are all PHP files located in this directory named in StudlyCaps casing.

### Additional Architectural Components
  • root - for files that are called by the app and are part of the main engine, i.e. config.php.
  • classes - self explanatory.
  • css - home for all cascading style sheets.
  • email - email templates and sandox related email configuration.
  • images - contains stagnant images and icons utilized within Worklist.
  • js - houses all javascript files.
  • tmp - contains composer file used during sandbox setup. Also used for caching requests to the status page.
  • uploads - used for images uploaded in the development application.
  • vendor - proprietary software utilized in the Worklist application.
## Naming ### Classes

Class names must be declared in StudlyCaps.

// PHP
class MyClass extends AnotherClass {}
// Javascript
var MyClass = {};
### Constants

Constants (both global and class constants) must be declared in all upper case with underscore separators.

define('CONSTANT_NAME', 'constant value');
const ANOTHER_ONE = 'thevalue';
### Class Properties, Variables & Methods

There is no specific requirement for using capitalization styles in class properties, variables or method names. Whatever convention is used for them, it should be applied consistently within a reasonable scope (at vendor/package/class/method level).

## File and Code Formatting ### Encoding

Files must use only UTF-8 without BOM. TAB characters should not be allowed, please use 4 or 2 characters indents (consistently within a reasonable scope) instead. Special/regional chars in the code should be properly escaped.

### Side Effects

Most PHP and Javascript files should declare new symbols or resources such as classes, functions constants, etc. and cause no other side effects. It's code should be run from the common bootstrap flow or from a specific point in the code. A file with "runable" code that declares resources (ie: a class) and also makes calls by itself (outside that class, without being called externally), should not be approved in a Code Review.

ini_set('error_log', 'php.errors'); // this is not allowed according to the context

/**
 * This class declaration is the only block that should live in this file 
 */
class MyClass {
    public function method() {
        // some code here
    }
}

$myObject = new MyClass(); // side effect, not allowed
### Markup Structure

Markup language files should be formatted according to its structure, keeping it readable by splitting child elements in new indented lines according to their parents and avoiding lines with a length longer than 128 columns.

### Source-only

Minified, compiled or unreadable/undiffable sources should not be allowed except for 3rd party dependencies and binary provided multimedia files, such as jpg/png images and mp3 files.

# Views, Content & Styling ## Content & UI

In Worklist, we strive to produce clear, attractive, and efficient end user UI's. This is, in our belief, as equally important as is readable code and data on our development end.

Using well known techniques plus some custom rules to fit our needs, we've established a simple way to accomplish separation of content, app logic and UI components, allowing us to produce blocks of code which are quick to review as well as modify.

### Markups: more content and less metadata

The markup doesn't need to be very dirty; getting the needed UI by making use of latest CSS advantages and a good use of Javascript is more important.

  • The DOM tree should be as simple as needed: Keeping a well structured markup and using element variations improves readability.

  • New IDs, classes and properties on elements should be avoided: Let's try to use the current ones already in the project and improve selectors to get to the desired paths in the DOM.

  • Respect layouts: in order to look forward to SEO improvements, outputted record layouts should keep the same structure as the data. This means that a developer should not print child components outside of his parent's block in the DOM according to the structure of its data.

Comparison Example:

<style>
  #whatever,
  .message,
  .boldtext,
  .content,
  .no-margin,
  .date {
    // ...
  }
</style>
<body id="whatever">
  <div class="message">
    <div class="boldtext">Title</div>
    <p class="content">
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
      tempor incididunt ut labore et dolore magna aliqua.
    </p>
    <p class="content no-margin">
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
      tempor incididunt ut labore et dolore magna aliqua.
    </p>
  </div>
  <p class="date">6 hours ago</p>
</body>

Could be improved and the UI should remain the same. Something like this:

<style>
  body,
  body > article,
  h3,
  article > h3,
  article > p,
  article > p + p,
  article > p + p:last-child {
    // ...
  }
</style>
<body>
  <article>
    <h3>Title</h3>
    <h4>6 hours ago</h4>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
      tempor incididunt ut labore et dolore magna aliqua.
    </p>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
      tempor incididunt ut labore et dolore magna aliqua.
    </p>
  </article>
</body>
## Styling Scopes ### Global and view-level rules

Except for some resources such as legacy rules (which should progressively disappear), the navigation bar, and the footer, there are two accepted scopes for introducing css rules to the worklist project:

  • Global: rules are put in files that are shared among most views in the project, i.e.: each rule in css/newworklist.css affects all Views that use the NewWorklist layout.
  • View-specific: rules that affect a single view, each view that needs a specific styling should have this file with the rules inside.
## General Notes ### Commenting

One of //THE MOST IMPORTANT// things to remember while writing code is that you //must comment// your code!!!!

The code you write will be viewed, modified, copied, scrutinized, utilized, and reincarnated by dozens, potentially hundreds, of developers from around the world. Comments must be:

  • Well-written and descriptive, but brief.
  • Written in plain English.

Comments should be:

Dated using the date format specified in the Locale Standards section. Example: 05-APR-2014

  • Signed at the end with your sandbox username between less-than (<) and greater than (>) symbols. Example:
  • Describe parameter and function usage, as well as usage information (where applicable e.g. functions and classes)

Comments must not:

  • Begin with the hashbang (#) character
  • Exceed the maximum cs:formatting#Line Length (128)

When writing a comment that will fit on three or fewer lines, please use the double-forward-slash method. Example:

<?php
 // This is a comment that will exceed one line, but will be less than four lines in total,
 // which will include name and date. 05-APR-2014 <kordero>
 ?>

When writing code that will be in excess of three lines, please use a comment blocks. The format for such should adhere to the following standard:

<?php 
 /*Comments that will span multiple lines should be
 * placed in comment blocks such as this.  The first
 * Line should be a forward slash with two stars,
 * then a newline.  Commenting should not start with
 * the first line.  Each subsequent line should be
 * indented with a single space, then the asterisk
 * and a space, followed by the text of the comment.
 * Each asterisk in each subsequent line should
 * appear in-line below the first asterisk in the
 * opening line of the comment.  When closing the
 * comment block, the final asterisk should be placed
 * in line with the rest, followed by a forward slash
 * to close the block.  05-APR-2014  <kordero>
 */
?>

When appending to someone else's comments, add yours BELOW theirs, so that the comments read as a timeline. Do not edit the text of existing comments (including your own) for any reason, including typos. If the comment is incorrect, or is no longer applicable in any part, remove it and replace it with your own. If the updated comment area will exceed three lines, convert the old comments to a comment block as described above, and append yours beginning with a new line. For example:

<?php
 // This is a basic comment. 05-APR-2014 <joanne>
 ?>

Adding additional lines would then be cause for conversion:

<?php
 /* This is a basic comment.  05-APR-2014 <joanne>
  * When I wrote the comment earlier, it was just a
  * single line, but now I need multiple lines, so I
  * have converted this to a comment block.  Future
  * comments should be appended below my comments,
  * which creates a log.  05-APR-2014 <joanne>
  */
?>
Add a custom footer
Add a custom sidebar
Clone this wiki locally