Difference between revisions of "WebIssues/Guidelines"

Latest revision as of 20:44, 12 December 2011

This page contains a brief list of standards and conventions used within the WebIssues project.

Coding Conventions

Formatting guidelines:

• use four spaces for indentation (don't use tabs)
• use LF (Unix-style) line endings
• put spaces inside brackets and parentheses of expressions, function calls and statements
• put spaces after commas and around binary operators
• use single blank line to group statements together
• place the opening brace in the same line as the start of the statement
• place the opening brace in a separate line for class and function declarations

For more details look into the existing code and try to be consistent when adding new code.

Naming Conventions

General guidelines:

• Use camelCase for functions and variable names
• Use PascalCase for classes, types and constants
• Use ALL_CAPS for macros

Function names should generally start with a verb and class names should end with a noun.

There are some differences between client and server code related to compliance to existing coding conventions:

• In desktop client, the "get" verb is omitted from getter methods (according to Qt coding style)
• In server, classes use underscore in place of the path separators (according to Zend conventions, to make auto-loading easier)

Avoid short and meaningless variable names. Single character variables can only be used as loop counters.

File names can only contain lowercase letters, numbers, underscore and dash characters. In C++ code use .cpp and .h file extensions. In PHP code use .php extension only for entry scripts (i.e. scripts which can be invoked via URL); use .inc.php extension for non-entry scripts and .html.php for view templates.

Comments

Use javadoc-style comments for classes and their public and protected methods and constants. Provide short but meaningful description and document parameters and return values except when obvious (e.g. for getters/setters).

Prefer short, readable and self-documenting code and only provide additional comments when something is not obvious (e.g. workaround for a bug).

Project Philosophy

Below are some general design principles of WebIssues:

Universality

The goal of WebIssues is to support team collaboration and communication. It is not a specialized tool for project management, ticket tracking, etc. Therefore it offers great capabilities of customization, at the cost of some specialized features.

Usability

The usability theory discovered that creating software for a very small set of people will create software that is usable by a huge set of people. While creating software for just everyone will quickly make it so convoluted that is only works for a few people. All features should be simple, easy to use and understand and generic. Existing concepts should be reused whenever possible.

Portability

WebIssues should support Linux, Windows and Mac OS X, several database engines and web servers. Features that only work in a particular environment or depend on non open-source components should be avoided.

Backward compatibility

To minimize problems related to updating the client applications to newer version, only major versions of WebIssues can introduce changes which are not backward compatible with previous versions. The communication protocol must be carefully designed in order to allow adding new features without breaking compatibility.