Bennu Bird Media Coding Standard

charles.russell — Tue, 04/06/2010 - 02:13

Purpose
1. In any organization it is important to use established standards. It is also important that these standards be established early, have management buy in, and be clearly stated. In this document I am going to focus on implementation, specifically the coding standards. We will explore why this is important, provide links to established standards, and define our own extensions to the already existing standards. Other standards concerning project management, architecture and design will be stated in other documents.
Justification
1. There has been much research done on the maintenance and proper engineering of software whether it be for the Web or as a stand alone application. Much of this study is on why some projects succeed and others fail. These studies have resulted in many important insights but in this document we are going to focus on what is important in the maintenance of source code. Many people have done important work in this area some well known names include Jeffery Zeldman, Eric Meyer, Fredrick Brooks, Douglas Crockford. We are going to piggyback off this body of knowledge and adopt what has become accepted best practice in the writing and maintenance of code.
2. First we want to make sure that any code we write is cross browser compatible. There are many browsers and while there are some differences they do for the most part follow the World Wide Web Consortium (W3C) standards for XML, HTML, XHTML and CSS. Also the European Computer Manufacturing Association (ECMA) specification 262 is generally followed for what is generally called JavaScript. This is especially true for current browsers. Microsoft, a company notorious for not meeting these standards is now fully compliant with the W3C standards as of Internet Explorer 8.
3. Next we want to create well organized, easily readable code. This is often referred to as clean code. This reduces the overall costs to our clients because well commented code that is properly indented, and consistent in style will be easier to change, debug, and maintain. To do this and to keep code consistent the Drupal Association has established a coding standard for Markup, CSS, Javascript, SQL, and PHP. Because we are a Drupal shop we will code to those standards. Every language has certain styles associated with it, the Drupal Association has done a very good job of codifying this and adopting to the particularities of Drupal. We will expand a little beyond the Drupal standards to further improve our quality and later in this document we will state, fully explain and justify these extensions.
4. Because we intend to be standards compliant it is important that all code that we generate validate. Validation is a measure of how well you comply with the rules grammar of the markup or style language chosen. For historical reasons the browsers are very lax in how strictly the rules are enforced. The problem is there is not consistency between browsers in where to be lax. So why depend upon the fact that you can get away with not closing a <p> tag, just make sure you always do it and then you don't care. There are several validation tools available for XHTML and CSS but we will use the W3C validator as this is the source of the standard. In addition the the markup it is important that we also comply with the Web Content Accessibility guide lines. We will expand upon accessibility later because that is a very important subject in its own right.
5. One of the things being stressed for reasons of maintenance is the separation of the various client elements. These elements are the content(HTML), layout(CSS), and behavior(JavaScript). What this means is that each of these elements is contained in thier own file. This serves several important purposes:
  - Each element can be changed independent of the others. This means that you can change behavior without affecting content or layout. You can change the layout without affecting either the behavior or the content. You can probably deduce the next statement yourself. This means that you can share resources across multiple page even multiple sites. There is a term for this, Dry Code. Dry is an acronym for Don't Repeat Yourself.
  - Graceful degradation is another reason for doing this. We always want a functional site, no matter the condition. Features that are available now were not available in older browsers, sometimes companies will turn off their JavaScript for security reasons, some people turn off images. We always want as many features as the browser and users will give us but as a feature becomes unavailable we want to continue to provide as much functionality as we can. What this means is that if you have turned off JavaScript and CSS then the site will still display. It won't be as pretty and not as user friendly, but it will still work. This separation facilitates this type of web design in so many ways there are articles and books dedicated to this subject alone.
  - Sites written in this way lend themselves to better search engine optimization. Search engines look only so far into the text of a site to get information about the content. The less clutter you have the further into your site the spiders of the search engine will get.
  - Readability is another important reason. Think about a book that is written in four languages. Not separated as in a page in one language and the next a translation in another but totally jumbled. Within the paragraph you may start out in English, the next sentence would be in German, next would go to French for a while and finish in Spanish. Such a book would likely not be a best seller. If we do not find this acceptable in literature, why then do we accept this in code? We realize that in some cases, like the construction of templates that run on the server, this is unavoidable but why punish ourselves when we don't have to?
6. Since 2000 accessibility for the web and computer applications. This is not just for political correctness there are some very important financial considerations involved. According to an article ( A Brief Introduction to Disabilities) by the Trace Center at the University of Wisconsin. Approximately 3.4% of the US Population are legally blind. Another 1.8 million have other severe visual impairments like color blindness, farsightedness, and tunnel vision who are not legally blind. 8.2% of the US population have hearing problems for 2.4 million the problem is severe. I have not even touched upon those who have cognitive or physical disabilities. If you are in business would you want to reject 3 to 7 percent of your potential customers. By ignoring accessibility concerns you are doing just that. If the financial incentive is not enough there are now legal implications to this. In the United States we have the Americans with Disabilities Act companies with non-compliant websites are being sued and losing more often than not. To address this the W3C established the Web Content Accessibility Guidelines. The US Government amended the Rehabilitation Act so that all Federal Agencies meet a basic level of accessibility. These guidelines are in Section 508 of that act.
Standards
1. General Guidelines
  1. Every effort will be made to meet WCAG level A (things you must do) and level AA (things you should do). This includes attention to ARIA. Level AAA (things you may do) is more complicated and shall be addressed depending upon need and budget.
    1. The actual standard can be found at http://www.w3.org/TR/WCAG20/
      1. Quick reference can be found at http://www.w3.org/WAI/WCAG20/quickref/
        
        Wave at http://wave.webaim.org/ is a very good first cut validator.
  2. Drupal uses Doxygen to aid in documentation. This uses comment blocks within the code to document files and the design elements within them. The Drupal Standard for this is defined at Doxygen formatting conventions
2. Markup
  1. HTML/XHTML
    1. Bennu Bird will use the Drupal Markup Style Guide found at http://groups.drupal.org/node/6355 as the base guideline for markup.
    2. HTML does not do name spacing so to avoid conflicts with other possible elements we will precede name with an identifier unique to the project.
    3. Names will be camel cased or use an underscore in place of spaces with the initial character lower case.
  2. XML
    1. XML, unlike HTML, allows the creation of your own tags. When creating tags make sure that the element type properly describes the content.
    2. Use lower case attribute names to stay consistent with XHTML rules.
    3. Naming conventions will be the same as XHTML for class and Id attributes.
    4. All XML to be used for display will have a DTD or schema defined. It is important our sites are valid as well as well formed. This is less important for data transferred by AJAX but it still would be nice to have this done where practical.
3. CSS
  1. We will use the Drupal CSS coding standard as base this can be found at http://drupal.org/node/302199
4. Programming Languages
  1. PHP
    1. PHP will be coded using the Drupal PHP standard found at http://drupal.org/coding-standards
    2. Objects will follow the Drupal specification at http://drupal.org/node/608152
    3. Exceptions are also covered by the Drupal standard and this is found at http://drupal.org/node/608166
  2. JavaScript
    1. The Drupal JavaScript standard is at http://drupal.org/node/172169
    2. We will use initial cap with the rest of the name camel cased on any class name that is intended to be used with a new constructor.
    3. Lint is a term that describes a program to flag suspicious not portable constructs. More than any other language that I know of it is possible to do some very bizarre and non portable code. To reduce the amount of bad code Douglas Crockford developed a tool to flag problems in JavaScript. This tool is called JSLint and can be found at http://www.jslint.com/. All of our JS code will be run through this tool to assure the best constructed code possible.
  3. SQL
    1. Although less visible to most Drupal developers with the views module, SQL is still important when creating custom modules. The entire system is based upon a database and SQL is the language of data manipulations. It should hardly come as a surprise that the Drupal Association has developed a standard for this language as well. This can be found at http://drupal.org/node/559302

Add new comment

Bennu Bird Media

Bennu Bird Media Coding Standard

Purpose

Justification

Standards

General Guidelines

Markup

HTML/XHTML

XML

CSS

Programming Languages

PHP

JavaScript

SQL

User login