DESIGN PHILOSOPHY

Because Appleseed represents a huge potential for growth into many different directions, it's important that those involved understand the importance of a clearly defined design philosophy. In order to keep the project from becoming too unwieldy or from straying from it's original purpose, the project is being developed under the following five design philosophy points:

1. 'No Hacks' Policy.

The advantage of open source is that we are not on any kind of strict release schedule, so there is no good reason to implement a hack (1) to perform the function you want. If a change to the software requires a redesign, then either rethink the modification, or plan to redesign. Using code that 'just works', but is unmaintainable will only cause more problems in the future, so it's best to take the time to make the necessary changes.

2. A clean and functional user interface.

Interfaces can be nested up to three levels deep, using Switches, Tabs, and Sections (in that order). If your design requires you to nest any deeper than that, or if you have a large amount of sections clumped together, it's best to redesign your interface. Options should be clearly understood and labeled, preferably with an explanation nearby. The user should not have to go to the documentation to get a basic of idea what a setting does.

3. Full configurability.

From using CSS2 for layout, to placing all images in the 'themes' directory, to pulling all strings from the database, Appleseed's design is geared towards making sure an administrator never has to touch HTML or PHP code. The more configuration can be put into a web interface, the easier it will be for users to set up and configure an Appleseed site.

4. Social responsibility.

While other social networking websites treat the user as a marketplace commodity, by bombarding them with ads or allowing marketers to use information mined from their site, Appleseed is being developed with the exact opposite in mind: The user is a digital citizen, and interaction between people (and not marketers and advertisers) is the purpose of social networking software. All Appleseed versions that we release will take the principles of privacy and security for the user into strict consideration.

5. Interoperability.

All aspects of the site are being developed with the idea that they will have to interact with other servers running the software at some point. Although this feature may not make it into the software right away, the core design will always understand the necessity of interoperating with other Appleseed installations.

CODING STANDARDS

These are by no means the finalized coding standards, but they are a good starting point for anybody who wants to jump in to development.

1. The following naming conventions are in use:

aFUNCTION - a function name which is not attached to a class.
cDEFINITION - a class definition.
gVARIABLE - a global variable.
zCLASSNAME - a global class variable.
jFUNCTION - a javascript function.
bBUFFERNAME - an output buffer variable passed between sections.
pPARAMETER - a parameter for a function.

NOTE: Naming conventions are more centered around a variable's scope than the type of variable it is.

2. File extensions are as follows:

.php - PHP code.
.js - Javascript code.
.aobj - Reusable object (html, limited PHP, no logic)
.ainc - Appleseed include (reusable PHP code)
.afrw - Appleseed XHTML framework
.ainfo - Appleseed definition file

3. All strings should be pulled from the database using the $zSTRINGS->Display or the $zSTRINGS->Lookup function. This allows Appleseed to be more easily cusomized and translated.

4. Indentation should be set to two spaces.

5. Always use 'switch' statements as opposed to 'elseif'. Use nested 'if' statements sparingly.

6. 'Case' and 'break' on switch statements should be indented two spaces, and all code should be indented four spaces.

7. If a function can be attached to a class, attach it. If it can't be, then attach it anyways. If it still can't be, then make it a standalone function.

8. Keep a clear separation between implementation and presentation. This is done by putting all logic and database interaction into the code/ directory, and all presentation of data into the objects/ directory.

9. Always start logic sections on the same line as the logic. End all logical sections (ie, inbetween brackets) with a comment specifying what you are ending. For instance:

  if ($variable == TRUE) {

    echo "TRUE";

  } // if

10. Always comment your code. Always write code that's so clear as to not need comments. Comment your code anyways. Use a double slash // for all comments.

11. Include a copy of the GPL with your contact information at the top of every .PHP file in the code/ directory.

12. Always 'unset' a variable when you're done with it.

13. Always use a full '<?php' tag, and never the shortened '<?'.

14. Use the aINCLUDE function instead of 'include'.

15. All URL's should look like directories, and POST data should never be viewable by the uninquisitive user. Appleseed's security system is based on what 'directory' the user is viewing, so it's important to stick to this.

More coding standards will be listed as they're decided upon.

July 19, 2005 - Revision 0.1.1