CODING GUIDELINES FOR BLUESHOES DEVELOPERS
------------------------------------------

@author andrej arn <andrej at blueshoes dot org>
@version 4.2.6 updated 2002-12-20


basically...
we'd like to have a clean and professional, bug-free code. 
most ppl have different coding styles. and most think that "the other style" 
is very ugly. we don't want to force you changing your style. here is how 
we do it and like it:


o) We use capital letters for constants. e.g. define('CONSTANT', 1). 
   We also use the capital form of  TRUE, FALSE and NULL.
   
o) if a function is described to return bool, expect to get a real bool 
   (TRUE/FALSE) and not an int (0/1). so please code your functions and 
   methods that way. 
   
o) don't trust the return values from php methods. if they are stated 
   to return bool, they often return an int (0/1). so don't directly 
   return that from your functions, convert to (bool).

o) never ever use echo, print and die and the like inside your methods. 
   i mean for debugging and if something fails. use return.
   
o) this applies also for white spaces. if you start your file with anything 
   (an empty line) before the <?php tag, it will be sent to the client and 
   considered as output. this fucks up cookies etc. the same applies for 
   white spaces after the ?> tag. take care! a typical php newbie mistake.
   
o) everything should be as os independant as possible. including windows.

o) don't support php3. only code for the newest php release.

o) make the php exam. repeat it from time to time. (see the website)

o) code object oriented.

o) avoid setting vars in the global scope.

o) if you need to have one in global scope, prefix it with 'bs'. 

o) avoid using things from global scope inside methods. 'include' them 
   in the constructor. 

o) prefix classes with Bs_. this is a poor man's namespace.

o) name your files like the classes: a class named 'Bs_Something' will 
   have the file name 'Bs_Something.class.php'.
   
o) one class per file.

o) when you create a new instance of a class, *always* do it by reference:
   $object =& new SomeClass();
            ^---->this one
   this is *important*, *important*, *important*!!. trust me. if you don't, 
   you will after having strange bugs in your code and not finding them 
   for hours.
   also read http://www.zend.com/manual/language.oop.newref.php please.
   
o) please use the same coding style as it is already used, if you can. 
   i know that it sucks to change your coding style if you're used to something. 
   
   old: - a tab is 2 spaces
   new: - a tab is a tab, we set it to the width of 2, but feel free to 
          configure your editor to show it as 3, 4, 8, whatever.
   
   - a function is written like:
     function something(param, param) {
       //some code
     }
   
   - an if statement is written like:
     if ($this == $that) {
     } elseif ($this > $that) {
     } else {
     }
   
   - use spaces to separate: 
     $x .= $y . 'hello';   instead of   $x.=$y.'hello';
     exceptions are (for readability):
     - $array = array('key'=>'value', 'key2'=>'value2');
     - for ($i=1; $i<=10; $i++) {
     - function myFunction($a='default', $b='foobar') {

     
   - use studly caps (first letter of each word capitalized (but not the first one), 
     otherwise lower case, no underscores) for vars, functions (methods), lists, 
     anything that needs a unique name.
     class names go like 'Bs_SomeShit'.
     vars/functions/objects/db-names are started lowercase, class names/db-table 
     names are started uppercase:
     $someVarName         instead of   $some_var_name
     someFunctionName()   instead of   some_function_name()
     SomeObject           instead of   some_object
     this especially also applies for short forms:
     $someDbTable         instead of   $someDBTable
     $someHtmlString      instead of   $someHTMLString
     it is easier to read, and you can be sure how it was written. we think 
     it's better from experience. (an exception is the table field name/term 
     ID because of a naming convention.)
     
     these words are considered being one word, not two, and thus have no capital:
     - username
     - password
     - datetime
     - blueshoes
    
     a few other writings:
     - email       (not eMail or so, because someEmail will work while someeMail 
                    or someEmail or someEMail would break the rules.)
     
     please avoid something like '$conn1' ('$conn2', '$conn3' ...) because you cannot see 
     if it was $conn1 or $connl. see what i mean? (one or a small L)
     
   - don't use the fancy way pdf2html. it's kinda breaking the studly caps rule.
     it would be pdf2Html and then it's not that readable anymore because both 
     '2' and 'H' are "upper case". so always use pdfToHtml.

   - if in doubt, use java syntax/style.

o) learn what === and !== mean. rtfm.

o) passing by reference: In preperation for PHP 5 we recommend to take parameters that 
   are objects by reference e.g. 
     function foo(&$theObject, $theInteger){
       ...
     } 
   For other parmeters use the reference operator only for read only use. I'm not 
   sure how array's will be handled in PHP 5.
   
o) i (andrej) sometimes use the style:
   if (something && somethingElse && anotherThing) 
     thenDoThis($param, $param, $param, $param, $param, $param, $param)
   i know what it's not so nice. i do it when the if gets long and i don't want to 
   have it all on one line. 
   
o) in your classes, define all your class vars using
   var $something; 
   even if you don't set a default value. it will help maintaining the code.
   
o) document while you code. please document (phpdoc, like javadoc) your 
   functions, classes, methods, even class vars. i know that coders are always 
   in a hurry. but it will save a lot of time in the end! it looks like this:
   /**
   * what the function does in one line.
   * here goes some more detailed description on 0-n lines, if needed.
   * @access  [public|static|pseudostatic]
   * @param   [string|int|double|bool|array|object|mixed] $paramName  description  default value
   * @return  datatype  description
   * @throws  bs_exception
   * @see     someFunction()
   * @todo    description
   * @since   bs4.1, php4.3             (comma separated list)
   * @status  stable|experimental       (if not set then considered stable)
   * @pattern singleton|factory|mvc|observer|facade|...
   */
   function something() {
   }
   the description is treated as plain text, don't use html as you can do it with javadoc. 
   we don't like that.
   @pattern singleton means that the constructor returns a reference to an already existing 
   instance, if there is one.
   
o) write ecg classes for your classes. they will serve other coders as examples 
   and make the code more safe. especially when it is installed on other os'es, 
   when new php/apache/mysql/... versions come out etc.
   see naming for a definition of ecg.
   
o) don't eat junk food and never drink Red Bull at night. pizza is ok. :)

o) don't use underscores _ in databases (table names, field names). they are 
   reserved for something special (relations).
   
o) don't use the numbers 2, 3 and 4 inside of db table names. they are reserved 
   (for relations).
     
o) associative arrays are called 'hash', zero-based arrays are called 'vector'. 
   please use these terms. undefined arrays are called 'array', of course.

o) use the term 'function' for 'structured' procedural code. use the term 'method' 
   for functions inside classes. don't use the terms 'procedures', 'subs', 'routines' 
   etc. sam: "methods are verbs, classes are substantives." :-)
   
o) when you return inside a switch or something, write a brake also. example:
   switch ($x) {
     case 'hello':
       return TRUE;
       break;
   }
   this way it will be harder for someone to 'implement' bugs into your code.

o) avoid buggy code. for example if you're not 100% sure that a var is an array, 
   do is_array(), sizeOf($array) and such.
   
o) Until PHP 5 comes up with try-catch use the do-while(FALSE) try-catch code, 
   something like:
     do { // try block
       $isOk = someFunction();
       if (!$isOk) break;
       $isOk = otherFunction();
       if (!$isOk) break;
       //...
       $isOk = TRUE; //everything worked
     } while (FALSE);
     if ($isOk) echo 'yeah';

o) form your var declaration blocks etc in a nice way: (note the extra spaces)
   $a        = 'hello';
   $bbbb     = 'world';
   $cccccccc = 'foobar';
   
o) mostly use foreach instead of while-list to loop arrays. see sam's php-bench.
   
   note: there are also, and i like them (andrej)
   while (list($k,) = each($a)) {
   while (list(,$v) = each($a)) {

o) never ever use magic quotes, it's a bad hack and even worse: it's on by default! 
   check your php.ini, look for "magic_quotes_gpc". it should be set to Off, 
   not On. (magic_quotes_gpc = Off)

o) make sure your code runs error free even if warnings and notes are enabled.

o) use the new superglobals (_GET, _POST etc), make sure your code works even if register_globals is off. 
   and we highly recommend to set register_globals to off. (need php 4.1 or 4.2 for that)

o) javascript classes are named like in php, for example "Bs_FormFieldSelect.class.js". if it's a lib then 
   it goes like Bs_FormFieldSelect.lib.js. a lib is simply a collection of functions for a special task, 
   so not oo-code.

o) if you change something in code someone else maintains (and/or you're not in the @author of the class 
   or the function) then add your comments along with the date and your name, example:
   someCode(); //i did this because of that. 2002/10/16 --andrej

o) don't add email addresses in plain text. even the phpdoc comments in the code get indexed, and thus 
   could be spidered by email spiders. please use "user at domain dot com" which makes it a lot harder to 
   parse.

o) i started to name files that are seen by search engine spiders like file_name because then the text is 
   better indexed and results in better se positions. example: php_framework.gif is better than 
   phpFramework.gif. and don't forget the alt text...


o) naming

   block        the block xml itself.
   blocebo      placebo & block => blocebo (previous: blockbase)
                placebo is medicine that does nothing. this block does not do much either, it just 
                has a name (and maybe a part) attribute, that's it.
                used in xlay xml layout files. needs a blockref in the page or pagelet.  
                example: <bs:blocebo name="menuSection" part="default" type="design"/>
   blockref     used in xpage or xlay xml files.                                         
                example: <bs:blockref name="menuSection" source="file" node="" version="x"/>
   innerblock   a bs block inside an existing tag. used in layout files.                
                example: <img width="50" bs_blockref="node=''; name='logo'; version=''; part=''"/>
                this exists with bs_blockref and bs_blocebo.
   
   ecg          ElectroCardioGram
                in the code base you'll find many subdirectories with that name. there are php code 
                files that test our code. we thought calling them just 'test' would not give them 
                the honor they deserve, and prolly someone would just delete them. the ecg tests 
                show a sysadmin very fast what's not working (anymore) on his system, for example 
                after the installation or after a php upgrade or whatever. 
                
   whtml        wysiwyg html. it's a mime type in blueshoes. it means that the block [part] may be 
                edited using wysiwyg. so it's not xml compliant. a synonym would be "crappy html".
   
   URL: (see Bs_Url.class.php and its methods)
   scheme://user:pass@host:port/path?query#fragment
   example: url https://bill:gates@order.blue-shoes.com:81/forms/form.php?lang=fr&sid=456456#address
     scheme     = https
     host       = order.blue-shoes.com
     port       = 81
     user       = bill
     pass       = gates
     path       = /forms/form.php
     query      = lang=fr&sid=456456
     fragment   = address
     domain     = blue-shoes.com
     directory  = /forms/
     file       = form.php
   
   xpv stands for xPointer vector. match always returns an array, so xp is always an array, maybe an empty one.
    
   UID          Unified ID. the uid of a block can be in an url-style, and is parsed and used as array 
                internally. 
                
                the keys 'p' (part) and 'm' (mime) only apply for blocks. if they are there for other things, 
                eg layouts, they should be ignored.
                
                url-style  : n=name;p=part;l=language;v=version;m=mime
                             example: n=/some/path/main;l=de;v=1.1.1
                array-style: KEY          EXAMPLE  DEFAULT
                             name         main             
                             part         short    default
                             language     de-ch    -conf-file- (usually en)
                             version      1.1.1    x (= newest)
                             [mime                               ]
                
                a filename now looks like: /path/to/file/nameOfObject.lang.version.mime.xblock
                examples:
                /path/to/file/foo.en.1.1.1.html.xblock
                /path/to/file/bar.de.1.5.2.xlay
                /path/to/file/bar.xx.2.1.14.xpage
   
   
* [*1] 
*   Abstract class (as defined by JAVA)
*   An abstract class may contain abstract methods, that is, methods with no implementation.
*   In this way, an abstract class can define a complete programming interface, thereby providing
*   its subclasses with the method declarations for all of the methods necessary to implement that
*   programming interface. However, the abstract class can leave some or all of the implementation
*   details of those methods up to its subclasses.