"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "ocs-2.1.0-1/docs/README-DEV" of archive ocs-2.1.0-1.tar.gz:

    1 	====================
    2 	=== Coding Standards
    3 	====================
    4 
    5 
    6 Contributing Code
    7 _________________
    8 
    9 The PKP team is happy to accept patches in the public "OCS Development" forum
   10 at <http://pkp.sfu.ca/support/forum/viewforum.php?f=3>. If you would like to
   11 have your patch included in the OCS codebase, we suggest discussing it with
   12 the OCS team before implementation to ensure that it suits upcoming development
   13 plans.
   14 
   15 For code that is intended for inclusion in the main codebase:
   16 * Patches against a current CVS checkout are preferred; alternately, patches
   17   against the most recent release version are acceptable.
   18 * Unless agreed with the development team, users should be able to toggle
   19   contributed features between enabled and disabled with a single setting; the
   20   system behavior should not be modified when the feature is disabled.
   21 * The feature should be suitable for situations where very distinct conferences are
   22   hosted within the same deployment; i.e. settings should generally be conference-
   23   level, not system-level.
   24 * The design patterns used in OCS 2.x should be understood and adhered to.
   25 * Localization standards should be maintained.
   26 * Database IDs should be checked as in the current codebase.
   27 * XSS (cross-site scripting) attacks should be checked as in the current
   28   codebase.
   29 * Contributors are responsible for writing code compatible with the primary
   30   platforms listed in README.
   31 * Contributions should be delivered to the team via the public "OCS Development"
   32   forum as a patch.
   33 * OCS 2.x management features should be kept in mind, such as upgrade and
   34   installation; all database schema information should be maintained in the
   35   dbscripts/xml/ocs_schema.xml file; etc.
   36 * The development team is happy to review contributed patches, but we have a
   37   limited amount of time to spend integrating patches with the codebase or
   38   modifying contributed code. If aspects of the code need work, we would rather
   39   inform the presenter and have them perform the modifications.
   40 
   41 For contributions that are distributed separately as patches or plugins:
   42 * If contributors haven't met all the conditions above, they are welcome to
   43   distribute additional features as patches or plugins. However, the OCS team
   44   won't be able to provide support in this case.
   45 * If the option is available, coding a feature as a plugin is the preferred
   46   method. The OCS team is continuing to refine the plugin infrastructure and
   47   welcomes discussion with plugin developers.
   48 
   49 
   50 General Conventions
   51 ___________________
   52 
   53 
   54 Editors
   55 -------
   56 * Tabs: Configure your editor to use tabs instead of spaces for indentation.
   57 * Linefeeds: Your editor must save files using UNIX linefeed format (not DOS
   58   CR/LF or Mac CR format).
   59 * Ensure your files end with a linefeed if your editor does not automatically
   60   add one.
   61 
   62 
   63 Indentation style
   64 -------------
   65 * Always include braces even in cases where they are optional.
   66 * Use K&R indentation style.
   67 * For example:
   68 	if (condition) {
   69 		...
   70 	} else {
   71 		...
   72 	}
   73 
   74 
   75 Naming Conventions
   76 ------------------
   77 * Use descriptive names. One character names are only acceptable as index
   78   variables in for loops.
   79 * Variable and function/method names (excluding constructors) should start with
   80   a lowercase letter and capitalize all other words.
   81   E.g., $myVariableName; function myMethodName() { }
   82 * Class names should start with a capital letter and capitalize all words.
   83   E.g., MyClassName
   84 * Constant names should be capitalized with words separated by an underscore. In
   85   general, constant names should also be prefixed with the package/class name to
   86   avoid collisions. E.g., ROLE_ID_DIRECTOR
   87 
   88 
   89 Comments
   90 --------
   91 * PHPDoc/Javadoc-style commenting is encouraged. See <http://www.phpdoc.de/>
   92 * For example:
   93 	/**
   94 	 * My method.
   95 	 * @param $foo string
   96 	 * @return boolean
   97 	 */
   98 	function myMethod($foo) {
   99 		...
  100 	}
  101 
  102 
  103 PHP Tags
  104 --------
  105 * Use the <?php ?> tags to enclose PHP code instead of the abbreviated <? ?>
  106   form.
  107 * Ensure that each opening "<?php" tag is followed by a closing "?>" tag (i.e.,
  108   do not omit a trailing "?>" at the end of a file even though the PHP parser 
  109   does not strictly require it).
  110 
  111 
  112 Quoting Strings
  113 ---------------
  114 * Use single quotes (') instead of double quotes (") to quote strings unless the
  115   string contains variables or escape sequences. Single quotes are slightly more
  116   efficient since PHP does not have to perform variable interpolation.
  117 
  118 
  119 Error Level
  120 -----------
  121 * Code must not produce any error or warning messages with the error_reporting
  122   level set to E_ALL (this is the default level set in includes/driver.inc.php).
  123 * This means using $array['key'] rather than $array[key], not using
  124   uninitialized variables, etc.
  125 * Note that this means that "@" should not be used haphazardly to suppress
  126   error messages.
  127 
  128 
  129 Global Variables
  130 ----------------
  131 * Code should not rely on register_globals being enabled.
  132 * GET/POST/Cookie variables should be accessed through the appropriate helper
  133   function.
  134 
  135 
  136 Other PHP Conventions
  137 _____________________
  138 * The inline form of if/else is acceptable for small statements (e.g.,
  139   assignments) only. E.g., $foo = $bar ? 1 : 0;
  140 * Use spaces between tokens. E.g., $foo = 1; $i > 0
  141 * Compatibility with PHP >= 4.2 (including PHP 5) is required. Appropriate
  142   abstractions should be used around non-backwards compatible code (e.g., using
  143   function_exists() to check for an available function and using an alternate
  144   implementation if it does not exist).
  145 
  146 
  147 HTML/XML
  148 --------
  149 * HTML should be XHTML-compliant as much as possible. E.g., use "<br />" instead
  150   of "<br>".
  151 * Tag names should be lower case.
  152 
  153 
  154 SQL
  155 ---
  156 * Use spaces between tokens. E.g., "column = ?" instead of "column=?"
  157 * Uppercase SQL keywords. E.g., INSERT, UPDATE, etc.
  158 * Long SQL statements should be logically broken up into multiple lines.
  159 * SQL INSERT statements should always specify the column names.
  160 * For example:
  161 	INSERT INTO mytable (x, y, z)
  162 	VALUES (?, ?, ?)
  163 * All SQL queries should be compatible with at least the versions of MySQL and
  164   PostgreSQL supported by the application. Although vendor-specific SQL
  165   expressions should be avoided, a record should be kept of any non-portable SQL
  166   that does get used (e.g., by filing a bug report).
  167 
  168 
  169 OCS Conventions
  170 _______________
  171 
  172 CVS
  173 ---
  174 * A web interface to the CVS repository is located at <http://pkp.sfu.ca/cvs/>.
  175 * A brief log message describing the changes made must be included with all CVS
  176   commits.
  177 * Whenever possible, CVS commit log messages should include "#BUG_ID_NUMBER#" to
  178   reference a Bugzilla report at <http://pkp.sfu.ca/bugzilla/> (it will be
  179   automatically linked when viewing a log in CVSweb).
  180 
  181 
  182 File Header
  183 -----------
  184 * PHP files should begin with a header similar to the following. Non-PHP files
  185   should begin with a similar header adapted to the appropriate comment style.
  186 
  187 /**
  188  * @file FILENAME.inc.php
  189  *
  190  * Copyright (c) 2000-2008 John Willinsky
  191  * Distributed under the GNU GPL v2. For full terms see the file docs/COPYING.
  192  *
  193  * @package PACKAGE
  194  * @class CLASS
  195  *
  196  * DESCRIPTION.
  197  *
  198  * $Id: README-DEV,v 1.6 2008/04/04 17:06:48 asmecher Exp $
  199  */
  200 
  201 
  202 Database Queries
  203 -----------
  204 * SQL queries should use the ADOdb abstraction layer.
  205 * SQL should use placeholders for variables.
  206 * For example:
  207 	$dbconn = $DBConnection::getConn();
  208 	$result = $dbconn->execute('SELECT x FROM mytable WHERE y = ?', array($y));
  209 	$result = $dbconn->execute('INSERT INTO mytable (x, y) VALUES (?, ?)', array($x, $y));
  210 * Only portable, standards compliant SQL should be used - compatibility with
  211   MySQL >= 3.23 (including 4.x), and PostgreSQL >= 7.3 is required. If database
  212   specific logic cannot be avoided it should be abstracted into DBConnection or
  213   ADOdb.
  214 
  215 
  216 Direct Access Objects
  217 ---------------------
  218 * DAO classes should be used to encapsulate all database calls.
  219 * Use DAORegistry to retrieve a reference to a DAO object.
  220 * For example:
  221 	$sessionDao = &DAORegistry::getDAO('SessionDAO');
  222 * DAO classes are expected to handle date/datetime format conversion between the
  223   database and PHP, and insertion ID retrieval for sequenced records;
  224   abstractions are provided in the base DAO class.
  225 
  226 
  227 Templates
  228 ---------
  229 * HTML output in PHP code should be kept to a minimum.
  230 * HTML output should come from the Smarty template abstraction layer.
  231 * The template engine supports basic conditional logic and loops and can access
  232   objects and arrays, but the complexity of the business logic used in templates
  233   should be minimized.
  234 * Basic template skeleton:
  235 
  236 	{**
  237 	 * FILENAME.tpl
  238 	 *
  239 	 * Copyright (c) 2000-2008 John Willinsky
  240 	 * Distributed under the GNU GPL v2. For full terms see the file docs/COPYING.
  241 	 *
  242 	 * DESCRIPTION.
  243 	 *
  244 	 * $Id: README-DEV,v 1.6 2008/04/04 17:06:48 asmecher Exp $
  245 	 *}
  246 	{assign var="pageTitle" value="user.userHome"}
  247 	{include file="common/header.tpl"}
  248 	...
  249 	{include file="common/footer.tpl"}
  250 
  251 
  252 Authorization
  253 -------------
  254 * Use methods in Validation class to check user credentials.
  255 * For example:
  256 	Validation::isLoggedIn();
  257 	Validation::isAuthorized(ROLE_ID_CONFERENCE_MANAGER, $conferenceId, $schedConfId);
  258 	Validation::isConferenceManager($conferenceId); [ preferred to isAuthorized() ]
  259 
  260 
  261 Localization
  262 ------------
  263 * i18n strings are defined in locale/<locale_key>/locale.xml.
  264 * Key names should be in the form "sectionname(.subsectionname)*.name".
  265   E.g., "manager.setup.conferenceTitle"
  266 * Use {translate key="my.key.name"} in templates to translate i18n keys.
  267 * Use the String wrapper class in place of the built-in string
  268   manipulation/regexp routines when handling data that could potentially be in
  269   UTF-8 (e.g., user input, parsed user files, etc.).
  270 
  271 
  272 Input Validation
  273 ----------------
  274 * User input should be properly validated/escaped (do not rely on
  275   magic_quotes_gpc being on or off).
  276 * For example, in template forms:
  277 	<input type="text" name="title" value="{$title|escape}" />
  278 * Retrieving user input:
  279 	$foo = Request::getUserVar('foo');
  280 * Escaping habits in order of precedence:
  281   - Manager's Step 5 text fields: No escaping performed
  282   - Abstracts, notes, comments, emails: {$field|strip_unsafe_html|nl2br}
  283   - Database IDs safely fetched from DB: no escaping necessary.
  284   - Mailing Address fields: {$mailingAddress|escape|nl2br}
  285   - Biography fields: {$biography|escape|nl2br}
  286   - Custom issue or article IDs in URLs: {$pageUrl}/.../{$customId|escape:"url"}
  287   - Date fields: Use date_format.
  288   - Comment fields: (to be filled in)
  289   - Multi-line fields inside textarea tags: {$field|escape}
  290   - Multi-line input fields that are filled in by the Manager or Site Administrator: {$field|nl2br}
  291   - All other fields: {$field|escape}
  292 
  293 Note that these should apply to parameters supplied to {translate key="..."} and
  294 {mailto address="..."} calls, e.g
  295 {translate key="my.key.takes.parameter" myParam=$myVar|escape}
  296 
  297 
  298 Other Tips
  299 ----------
  300 * Use Request::redirectUrl($url), or better yet, Request::redirect(...) for
  301   HTTP redirects instead of header('Location: ...');
  302 * For additional coding convention information, see the OCS Design Document
  303   at <http://pkp.sfu.ca/ocs/OCSTechnicalReference.pdf>.