ZenPhoto

1. Coding style
2. Commenting and documentation
3. Nightly builds
4. Subversion (svn)

Coding Style

Zenphoto code follows some basic style guidelines. We essentially use the 1TBS variant of the K&R notation C-code syntax, for example:

function foo($bar) {
 if ($bar == 2) {
   return $bar;
 } else if ($bar < 2) {
   while($bar < 2) {
     echo $bar;
     $bar++;
   }
 }
}

This is a fairly standard formatting for PHP code and makes things nice and readable.

A few rules:

• Spaces should be used liberally. Eg: if($x == 2 || $y == 3) and not if($x==2||$y==3).
• Indentation should be hard tabs, not space-emulated tabs.
• Always use variable and function names that make sense and are self explanatory. Eg: $album_name and not $n
• $underscored_variable_names are preferred. Global variables should always be named like $_zp_something
• camelCaseFunctionNames() are preferred. Example: printImageTitle()
• Try to make your function names “speaking”, so the name says what it generally does.
• Function that just get data without printing should be prefixed with a “get” and function that echo something with “print”. Examples:
  • getImageTitle(): gets the title to be passed to a variable for processing.
  • printImageTitle(): echos the title directly.
• Don’t use PHP “short tags” like <? in themes and plugins whereas the correct syntax shoud be <?php as they may not be usable on certain strict PHP installations

And a few guidelines for coding in general that we encourage:

• Use generalization and abstraction. DRY! (Don’t repeat yourself).
• Keep it simple – if something seems too complex it probably is.
• Keep efficiency in mind – try not to put filesystem operations in nested loops, for example.
• Write clean code! Make things readable and understandable.
• Comment your code so that others can understand it. Remember we are open source.

Commenting and Documentation

Zenphoto uses PHPDoc to generate function and class documentation. This works well because the documentation is both in-line with the code, and browsable externally as a reference.

Zenphoto’s PHPDoc reference is on the main zenphoto.org site.

Instructions for how to form comments for functions and variables can be found on PHPDoc’s site here. Or take a look at Zenphoto’s code for examples.

Also don’t forget to comment other parts outside the PHPdoc comment blocks if necessary.

Nightly Builds

If you would like to simply test the development releases of Zenphoto between releases, you can use a nightly build. These are created from the current SVN trunk every 23:00 Pacific Standard Time.

The nightly builds are located at: http://www.zenphoto.org/files/nightly

Warning: These packages may be unstable and haven’t necessarily been tested. Use them only if you wish to help test new features and give us feedback.

Subversion (svn)

Zenphoto uses Subversion for revision control, and we like it a lot. You can browse the repository by using the Trac source code browser, which is very useful for seeing diffs and revisions in real time.

The SVN repository is located at: http://www.zenphoto.org/svn

And the repository structure is fairly standard:

• /trunk is the current version in development, where we do most of our work.
• /branches are versions with less stable code in heavy development, which may be later merged into trunk.
• /tags are snapshots of the trunk at any given time, usually all version releases, or pre-merge from a branch.

If you want the “Latest SVN Code” to work with, you should “check out” the repository locally by running:

SVN checkout http://www.zenphoto.org/svn/trunk

If you just want to run the latest code without all the SVN metadata files, you should do an export:

svn export http://www.zenphoto.org/svn/trunk zenphoto/

And finally, if you’re going to be working with the SVN copy a lot, you should get a good SVN client for your operating system. We use these ourselves:

• Windows: TortoiseSVN
• Mac: snvX

Recommended additional read: General contributor guidelines