page 1 of 12 Table of Contents:
1. Introduction/Rationale
2. Who should use these guidelines? 3. Who should read/use this document? 4. Coding Conventions – General
4.1 Default Language
4.2 Name, Author Information, Versioning/Tracking Changes 4.3. Commenting code
4.4 Naming Conventions Variables Constants
Loop indices and counting Functions
Structures 4.5 Code Layout
4.5.1 Indentation
4.5.2 Parenthesis () and braces {} 4.5.3 Token separation (spacing) 4.5.4 Operator precedence 4.6 Documentation
4.7 Testing
5. Coding Conventions – Security
6. Coding Conventions – by programming language a. HTML, DHTML, CSS b. XML, XSL, XSLT c. PHP, ASP, JavaScript d. Flash e. Database Queries 7. Tools/material/references available
page 2 of 12
1. Introduction/Rationale
These guidelines are meant as a reference for all internet-related development. Since UNICEF’s projects are increasing in both scope and complexity it is important to establish a universal, easy-to-follow style that will be followed by both in-house and outsourced developers. Adhering to these guidelines will facilitate maintenance and upgrades of code, and increase the transparency of the development process.
2. Who should use these guidelines?
The following guidelines are meant as a reference for internet developers. While there is no easy standard to enforce on web development the rules that are listed in this document are aimed to be general enough as to not infringe on individual coding style, and specific enough to ensure that organizational documentation needs are met. The guidelines should be followed by all in-house and outsourced internet developers.
3. Who should read/use this document?
This document is aimed primarily at developers. However, it is recommended that everyone involved in the UNICEF internet upgrade project is familiar with these guidelines, knows where they are available, and who they should be disseminated to. In this respect, sections 1 – 5 will be particularly valuable to non-developers, while section 6 contains more specific, concrete coding examples. Developers should use the entire document as a reference.
4. Coding conventions – General
As mentioned in section 2, agreeing on a universal standard for web programming is not easy due to the vast differences in programming languages that are used. Between server-side, client-side, hyper-text, query, and countless other variations there seems to be little common ground. However, the need to use coding conventions outweighs these potential problems. As with everything web-related, the coding conventions or standards will require a certain dose of flexibility and understanding from both the developers, and the organization.
This section outlines the general principles that all developers working on the UNICEF website should follow. A more detailed break-down with examples according to programming languages can be found later in the document. However, this is probably the more valuable section, as it covers the logic behind our requirements and needs when it comes to coding and documentation style.
4.1 Default Language
Unless otherwise specified, the default language used for programming comments and other documentation material is English.
4.2 Name, Author Information, Versioning/Tracking Changes
A unique name for any program is recommended. The name of the program should be indicative of its functionality, and clearly indicated in the file name, the package name (if there’s more than one file), and the documentation material. Author information for proper crediting is also recommended, as well as an email address in case future contact with the author is needed. In lieu of a name, a version number can be used for modifications on existing code. It is recommended that these items are included in headers (initial comments) in files that are part of the program that is being developed. Since this approach may not be practical for all files (such as .html where comments of this type would increase file sizes substantially), please include a readme- or help- type of file with your work where these
page 3 of 12
items would be indicated. Please refer to the example below for a sample file heading, and ideas on what other information would be useful to include in your programs:
Example: Sample program header <!— ********************** Program Name:
Version: Description: Last Modified On: Author [Name/Email]:
********************** --> 4.3. Commenting code
Comments are very important for code readability and are strongly encouraged. Generally, the more comments, the better. However, for some programming languages extensive comments may increase file size and be counter-indicative. Here are some suggestions on commenting code:
-- Clearly identify what a particular chunk of code does. Describe the idea behind it, don’t verbalize the code (“if the number of items is greater than the maximum size of the array” is much more useful than “if a is greater than b”). -- Separate code segments with your comments to simplify searching through the code (i.e. include the line
<!-- *** global variables and constants *** before the chunk of code dealing with global variables and constants). -- Unless absolutely necessary do not interpolate your code with comments. It is much easier to understand and read code if the comment precedes it. In-line comments are therefore discouraged.
-- Indicate if you are relying on external elements – for instance, if you are using JavaScript functions imported from an external JavaScript file.
-- Indicate dependencies: if your code makes modifications to global variables, global files or other bits important for re-use, indicate these changes in your comment.
4.4 Naming Conventions
In general, use clear and logical names, i.e. image_size, max_width, etc. The code you write should be in lower case, unless specified differently (this rule does not apply to constants, database queries, and certain pre-defined objects that may use mixed case). If the name contains more than one word, please use an underscore to separate. Common abbreviations such as min or max are allowed but it is advisable to always use the whole word. For specific considerations in addition to these general principles, please see below:
Variables
all lower case, indicative of the intended value of the variable
distinguish global variables by preceding them with g_ [i.e. g_standard_width]
check for reserved words in the language you are developing and make sure that you are not overriding any with your variables’ names
Constants
constant names should be in capital letters, i.e. LENGTH
alternatively, keep the constants lower case but precede them with c_ [i.e. c_length]
check for reserved words in the language you are developing and make sure that you are not overriding any with your constants’ names
page 4 of 12
loop indices are encouraged to have short and non-descriptive names
please use i as the iterator in the outermost loop, j in the next inner loop, k in the one after, etc. skipping l (lowercase L) since it may resemble the number 1 and be difficult to read.
for other types of counters or iterators, please follow general rules for variables. Functions
all lower case, names indicative of functionality
for clarity, precede all function names with fn_ [i.e. fn_reset_image_size] Structures
it is advisable to indicate the type of structure you are using in the name of the structure. For example, all ASP recordset names should be preceded with rs_.
4.5 Code Layout
4.5.1 Indentation
use tabs instead of multiple spaces indent all nested structures
indent opening and closing braces to match the first and last statement of the function or block they encapsulate
4.5.2 Parenthesis () and braces {}
parenthesis () should always be used for if, while, for, etc. blocks, even in places where omitting them would not cause a parsing/compilation error. This will facilitate code maintenance in the future. there should be no space between opening and closing parenthesis.
separate the code enclosed in the parenthesis by a space (see example below). braces {} should always be on separate lines (see example below).
Incorrect Correct for ( $i = 0; $i < 10; $i++ ) { count($i); } for ( $i = 0; $i < 10; $i++ ) { fn_count ($i); }
4.5.3 Token separation (spacing)
please include one space on either side of a token in expressions, statements etc. The exceptions are commas (which should have one space after, but none before), semi-colons (which should not have spaces on either side if they are at the end of a line, and one space after otherwise).
functions should have one space between the function name and the opening bracket and one space between each argument, but no space between the brackets and the arguments.
individual conditions inside brackets in control statements (e.g. ($i < 9) || ($i > 16)) should not have spaces between their conditions and their opening/closing brackets.
Incorrect Correct
$i=0;
if( ( $i<2 )|| ( $i>5 ) ) compare( $a,$b,$c )
$i = 0;
if (($i < 2) || ($i > 5)) fn_compare ($a, $b, $c)
page 5 of 12 4.5.4 Operator precedence
always use parenthesis to make sure that correct operator precedence is ensured.
4.6 Documentation
Documentation is required for every code modification or new application that is submitted for use on the UNICEF website. In addition to good comments inside the code, a formal document detailing what the program or code modification does is required. This document is to be included with the distribution of the completed code, in the form of a readme .txt file, a .doc/.pdf or an HTML file. It is advisable to verify with the ITD team if the code in question has sufficient documentation before any installation takes place. This is especially important for all server-side scripts, and items that need to access and/or modify global server variables. The bare minimum for software documentation would be the following information:
Name of program, date of release, version number. Short description of what the program does.
Installation requirements (software that is required, and modifications that need to be made on the servers, etc. to make sure the program runs successfully).
List of all files included in the program package, all files that the program will need to reference or use. List of global server-side variables that the program will need to reference or use (especially if these need
to be modified).
List of functions that are native to the program, and their description.
List of all database connections and operations, grouped by type (insertion, deletion, etc.). List of known bugs/issues. Comments on how these were resolved. (See section 4.7 on Testing)
Contact information of the developer/company that has developed the code (please include support email or contact telephone number if such option was agreed).
4.7 Testing
Extensive testing and reporting/documenting of known bugs/issues is required for all code that is to become part of the UNICEF website. Developers are encouraged to test locally, and provide feedback to the in-house ITD team during development testing on the UNICEF network. Please bear in mind that UNICEF targets audiences around the world, and especially in countries where IT infrastructure is not as good as in the United States. With this in mind, please ensure the following:
any code that is developed needs to work properly on a variety of browsers. The shortlist is Windows IE 6, IE 7 and Firefox 1.5(see 4.9). The ITD team will update regularly in case browser compatibility needs to be ensured for other browsers and browser versions.
file sizes and functionality need to be developed assuming that users with slower internet connections will be accessing the pages in question. If possible, please test for transfer rates via 56k dial-up.
4.8 Screen Size
The standard width of all web products designed by UNICEF should be 762px wide to allow for people with 800x600 screen resolution to see the page without horizontal scrolling. If a page/site has to exceed 762px try to break the content into columns that display naturally on an 800x600 display without any content being cut off. For instance in a three column design have the first two columns be 762px and the third bee 200px.
4.9 Browser Support
The browser market is constantly evolving so all recommendations are based on a date. Supported browsers as of 27 July 2006 are broken into two levels of support as follows.
page 6 of 12 IE 7, Win XP, 98, 2000, Vista
IE 6, Win XP, 98, 2000, Vista Firefox 1.0x, 1.5, 2.0
2. Here are the browsers which we should check for compatibility, but less rigorously..
Legibility and functionality are the bare minimum requirements for these browsers, i.e. text must be readable, links/forms/other features should work (regardless of how they look).
Attractiveness and appeal are significant pluses. IE 5.5, Win 98, 2000
IE 5, Win 98, 2000 XP Safari
By following the coding conventions for xhtml and html and by using the @import method (as opposed the the link rel method) of attaching style sheets, all pages should degrade gracefully in older browsers.
5. Coding Conventions – Security
Depending on the programming or scripting language that you are using in your project, different security elements will be applicable. We suggest that you check with the ITD team for specific security restrictions, or request a summary document outside the scope of these guidelines that will outline the specific security-related settings that need to be put in place. These are especially important for any server-side programming or coding of applets, plug-ins and similar pieces.
In general, please ensure the following:
group your functions into include files rather than stating them explicitly throughout the project. use ‘worst-case’ error handling/reporting account for all possible errors.
always use local include files.
carefully document if your code is using global variables, system files, etc. include error-checking in your code.
set file permissions as restrictively as possible.
6. Coding Conventions – by programming language
XHTML, CSS, DOM Scripting
-- UNICEF codes in XHTML and tries to follow the W3C recommended web standards. Always include a DOCTYPE in your document and use the code validators on http://www.w3c.org to make sure code complies with web standards. Use lower case letters for code, and reserve UPPER CASE, Sentence case, and Title Case for possible text elements within your XHTML file.
Incorrect Correct
<DIV ID=”content”> <Ul>
<LI>
Content Goes Here! </Li> </uL> </Div> <div id=”content”> <ul> <li>
Content Goes Here! </li>
</ul> </div>
page 7 of 12
-- Use XHTML make sure that all tags have proper closing tags and that all elements are properly nested. For some tags, this is necessary for the XHTML document to render correctly. For others, it’s just good style. XHTML makes shifting to or using parts of the HTML code in XSL statements seamless, and common problems with parsing mixed HTML and XSL can thus be avoided. Proper nesting improves code readability.
Example: HTML tags that do not customarily require closing tags are made XHTML-compliant by adding a ‘closing’ slash to the original tag. For instance:
<div> <ul>
<li>
Example of correct XHTML code<br /> </li>
</ul> </div>
-- Use indentation to improve code readability, use tabs to indent every next tag. <table> and <tr> tags can be kept at the same level (see example on the next page).
Example: A nested table using proper indentation and spacing <table id=”table1”> <tr> <td> <table id=”nested_table1”> <tr> <td>
This is the content for ”nested_table1”. </td> </tr> </table> </td> <td> <table id=”nested_table2”> <tr> <td>
This is the content for ”nested_table2”. </td> </tr> </table> </td> </tr> </table>
page 8 of 12
-- Do not use line breaks within ‘structures’ – for instance, do not leave empty lines within <table> tags, but instead separate two <table>s at the same level by several spaces.
Incorrect Correct
<table border=”1”> <tr>
<td>
This is the content. </td> </tr> </table> <table border=”2”> <tr> <td>
This is content, too. </td> </tr> </table> <table border=”1”> <tr> <td>
This is the content. </td> </tr> </table> <table border=”2”> <tr> <td>
This is content, too. </td>
</tr> </table>
-- Do not separate <, >, or = by spaces from the code. Use quotation marks for attribute values. For /, separate only in XHTML-compatible closing tags, such as <br /> or <img src=”some_image.jpg” />.
Incorrect Correct < div id = main> <ul> < li > This is a table.<br> < / li > < /ul> </div> <div id=”main”> <ul> <li> This is a table.<br /> </li> </ul> </div>
page 9 of 12 CSS
-- Refrain from using in-line styles unless absolutely necessary. Instead, append CSS classes either to the (global) stylesheet file that is already included, or to the <head> section of the HTML file.
-- When naming CSS classes, please use descriptive names. If your classes are only to be used in a portion of the project, i.e. Afghanistan pages, create a unique 3-letter prefix (i.e. ‘afg’) and append to the names of your styles (for instance, afg_main_body). If you are appending the global CSS file (or the most-global file under your project) please sort the classes alphabetically.
-- Refrain from re-defining properties of general tags, such as <p>, <ul>, <table>, etc. Instead, use contextual selectors or if necessary create separate classes:
Incorrect Correct p {backgound-color:#B0B0B0;font-family:Arial;font-size: 16px} IDEAL #main p { backgound-color: #B0B0B0; font-family: verdana, san-serif; font-size: 1.2em;
}
ACCEPTABLE
p.main {
backgound-color: #B0B0B0; font-family: verdana, san-serif; font-size: 1.2em;
}
or
.p_main {
backgound-color: #B0B0B0; font-family: verdana, san-serif; font-size: 1.2em;
}
-- End all entries with a semi-colon, including the last lines in each class (see example in red above). Describe one property per line. Use a space between property_name: and property_value (see example above).
-- Use ems to define font sizes not pixels. This allows the size of the text to be resized in all browsers which makes websites accessible to all audiences.
-- Always include default font-family of serif or san-serif to accommodate computers that do not have the specified fonts installed.
--The default language versions are
XHTML 1.0 Transitional or Strict (http://www.w3schools.com/xhtml/xhtml_reference.asp) and
page 10 of 12
XML, XSL, XSLT
-- Use lower case letters for code (including attributes).
-- Always include version and encoding information, i.e. <?xml version="1.0" encoding="ISO-8859-1"?> at the beginning of the document.
-- Ensure proper nesting. Sub-elements should always be indented. Always quote attribute values:
Incorrect Correct
<root><child name=Unicef><subchild>…
</child> </subchild> <root> <child name=”unicef”> <subchild>
…
</subchild> </child> </root>
-- Explicitly define the namespaces that you are using, to avoid potential conflict (i.e. <element xmlns=”namespace”>).
-- Use of CDATA sections is encouraged where applicable, rather than escaping individual characters. -- The use of behaviors, and XML-based .htc files is at this stage discouraged.
-- Use xsl:stylesheet rather than xsl:transform for consistency.
PHP, ASP, JavaScript
-- Must be compatible with php 4.1.x -- Register globals is off
-- Safe mode is on -- Short open tags is off -- Magic quotes is off
-- No assumptions are to be made about presence of any libraries -- Please follow all generally accepted best practices
-- If your code needs to access global variables, requires specific global settings, etc. please refer to language-specific additional coding guidelines to be provided by ITD, or get in touch with the ITD team directly.
Flash
-- publish for Flash Player 7
-- implement pre-loaders and develop assuming that many users will have connections of 56Kbps or less, optimize file sizes
-- provide a simple and accurate loading-status indicator
-- document major functionality, and submit source files (.fla) upon completion of project
-- separate design from content – all text fields (including labels on buttons) should be dynamic; use XML for content input
page 11 of 12
-- develop for a multi-lingual audience and ensure multi-lingual text/content input(determine need for multi-byte characters)
-- use comments
-- use standard interface conventions for usability purposes (scroll bars should look like scrollbars) -- provide obvious volume and mute controls if sound is used
--always leave browser chrome and back button functionality intact
Flash File Size: Due to the variety of uses flash has, a specified file size will not be recommended. However, loading speed for flash pieces are very important. All flash pieces must load within 10-15 seconds. Code can be broken into chunks and loaded dynamically after the user has started using/viewing the flash piece but it must be usable/viewable with 10-15 seconds assuming the user is using a 56k modem.
Database Queries
-- in all database queries SQL keywords should be in UPPERCASE. -- indentation is recommended, where applicable.
Incorrect Correct
select * FROM sw_screen_field sf, sw_field_props fp
WHERE SWKEY = 'UniqueName' AND
LOWER(SWVALUE) = 'sitecdbid' AND SF.SWSCREENFIELDID = FP.SWSCREENFIELDID SELECT * FROM SW_SCREEN_FIELD SF, SW_FIELD_PROPS FP WHERE
SWKEY = 'UniqueName' AND
LOWER(SWVALUE) = 'sitecdbid' AND
SF.SWSCREENFIELDID = FP.SWSCREENFIELDID -- all references to databases need to be properly documented (See section 4.6 on Documentation)
7. Tools/material/references available
Please find below a list of sites that may be useful for reference purposes. If you have specific questions related to applications developed for the UNICEF site, we encourage you to contact the ITD team directly via email.
HTML 4.01 (XHTML 1.0): http://www.w3schools.com/html/html_reference.asp http://www.w3schools.com/xhtml/xhtml_reference.asp CSS2: http://www.w3schools.com/css/css_reference.asp XML 1.0, XSL, XSLT http://www.w3.org/XML/ http://java.sun.com/xml/ JavaScript 1.5 http://www.mozilla.org/js/language/ http://www.php.net
page 12 of 12 ASP
http://msdn.microsoft.com/library/default.asp?url=/nhp/default.asp?contentid=28000522 http://www.asp-help.com/
