Zenphoto

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 </tt--> 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. Use the files with "development" in the name. The ones with "trunk" in the name are bug fixes to the current release. These builds are created from the current SVN every day at 23:00 Pacific Coast Time.

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

Warning: The development packages may be unstable and haven't been thoroughly 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/development is the development 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
  

Submitting changes

If you have changes you would like applied to Zenphoto releases procede as follows:

1. First try hard to find a way to implement your change as a plugin. We are committed to the "Zen" part of Zenphoto and would like to keep the mainline as trim as possible.
2. Develop your code based on the "development" branch of Zenphoto. The development nightly build is a good place to start.
3. When you have completed your testing and debugging, double check you code against the latest SVN or nightly build to be sure that it contains all current updates.
4. Create a Trac ticket for the feature/fix if there is not already one. Attach your edited files to the script. A good idea is to Zip them into an archive that reflects the Zenphoto file structure so we know exactly where they go.
5. Understand that for various reasons we may choose not to incorporate your changes into the official release. Most predominately this would happen if we feel we would not be able to provide continued support of the feature/changes.) If you developed a plugin, then we would encourage you to make it available to interested users.

Recommended additional read: General contributor guidelines