Getting started in development

From Docu Wiki

Development

Information:

Hacking Pelzini
Roadmap
Extensions
Using Subversion

Tracker:

External stuff:

The first thing you need is a working install of docu. See download and installation for more information. You will need a subversion checkout, you can download a snapshot or just checkout the source.

It is generally much easier to set up Apache, PHP and MySQL on your own machine (i.e. localhost). It's not necessary, but it speeds up development.

You can write patches for whatever you want. If they are small, and usually your first few should be, submit them to Many Small Patches.

If you have larger patches, submit them formally.

After a few patches, you can request subversion write access. I am quite liberal in granting this access, so don't be afraid to ask.

[edit]

Core design rules

These are the core design rules of docu:

Viewer and Processor separation: The code for the viewer and the code for the processor should be independent of each other. It should be possible for the viewer and the processor to exist in different directories, or even on different computers. It should even be possible for one to exist and not the other (in the case of archived documentation for example)

Design for multiple programming languages: The design of docu should be as generic as possible, with all of the programming-language specific features contained in the language parser.

Design for multiple outputters: While the default is a MySQL database, other databases are supported, and other output formats, including static formats (like TeX or DocBook) are planned - outputter specific code must be constrained to the outputter itself.

Development is foremost: Don't allow guidelines, process or silly rules of they get in the way of development.

These are the rules that govern how code should be written.

[edit]

Coding standards

The best way to show the coding standards is with an example.

<?php

define('THE_COOL_CONSTANT',    1);
define('THE_BETTER_CONSTANT',  2);

class FooBar {
  private $foo;
  private $bar;
  
  /**
  * This function does something cool.
  * It also does something else.
  *
  * @param string $blah The param
  * @return bool True or false
  **/
  function fooBarBaz($blah) {
    echo 'does something';
    echo "Blah is: {$blah}\n";
    
    if ($this->foo) {
      echo 'do something cool';
    } else {
      echo 'something else';
    }
    
    for ($j = 0; $j < $this->bar; $j++) {
      echo 'whee';
    }
    
    switch ($blah) {
      case 'whee':
        echo 'argh';
        break;
      
      case 'whoo':
        echo 'yum';
        break;
      
      default:
        echo 'default';
        break;
        
    }
    
    // This is so that the stuff will work properly.
    // This comment takes up a few lines but it still done with double-slash.
    if ($blah == 'cool' and $this->foo == 'yes') echo 'wow!';
    
    if ($whee) {
      echo 'aaa';
      echo 'bbb';
      
    } else {
      echo 'ccc';
    }
    
    return 42;
  }
}

?>

Indenting is with 2 spaces. Everyone has their opinion on indenting, this is mine.
Spaces are included in the indent for blank lines. highlight the above example to see what I mean.
Double slash for code comments. Use /* and */ to comment out code. In almost all cases commented out code should not be committed, thats what a revision system is for.
The exception to the above rule is example config files, which are coded to be usable and easy to understand even for non-developers.
If an if statement has multiple lines of code inside the braces, there should be a blank line before the } else {.