Difference between revisions of "WebIssues/Guidelines"

From MiMec
Jump to: navigation, search
(→‎Project Philosophy)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
This page contains a brief list of standards, conventions and guidelines used within the WebIssues project.
+
This page contains a brief list of standards and conventions used within the WebIssues project.
  
−
== Wiki ==
+
== Coding Conventions ==
  
−
Please use the [[MetaWikiPedia:Help:Link#Subpage_feature|subpage feature]] to split a page into a hierarchy of pages if there is a lot of information. All pages should related to WebIssues should be located under the WebIssues page in the hierarchy. Try to follow the existing structure of pages when adding new content. Put a short summary on top of each page and next to links to sub-pages.
+
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
  
−
Use the discussion pages for comments, opinions and suggestions, especially before making non-trivial changes to the main pages. This Wiki is accessible to everyone so it should be clean and representative. The main pages should contain only relevant and up to date information.
+
For more details look into the existing code and try to be consistent when adding new code.
  
−
== SVN Repository ==
+
=== Naming Conventions ===
  
−
Make sure committing to trunk won't break anything and consult all non-trivial changes with the project maintainer. For bigger changes use a separate branch which can be reviewed and merged back into trunk.
+
General guidelines:
 +
* Use camelCase for functions and variable names
 +
* Use PascalCase for classes, types and constants
 +
* Use ALL_CAPS for macros
  
−
== Coding Conventions ==
+
Function names should generally start with a verb and class names should end with a noun.
  
−
There are no enforced general conventions other than respecting the existing conventions in code which you are modifying. People responsible for particular projects may use whatever conventions they prefer as long as they are internally consistent.
+
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)
  
−
That said, it's obvious that all code that goes into trunk must be readable and well formatted. Always use meaningful names and avoid putting too much code into one line (for example, avoid nested function calls like <code>a(b(c()))</code>). Use comments describing the most important classes and functions (preferably in a way that API documentation can be automatically generated from it). Avoid meaningless comments in code - good code should be self-documenting.
+
Avoid short and meaningless variable names. Single character variables can only be used as loop counters.
  
−
As for the client and server, the most important rules are:
+
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.
−
* don't use tabs - indent code with four spaces
 
−
* put opening { brackets in the same line in statements (if, for, etc.) but in the next line in declarations (classes, functions)
 
−
* use spaces inside () and [] brackets, after commas and around binary operators, for example <code>foo( bar + 3, "hello" )</code>
 
  
−
== Project Organization ==
+
=== Comments ===
  
−
The WebIssues system is divided into several separate projects and each of them has a maintainer who is responsible for technical design (defining modules, classes, patterns, practices etc.) and organization of the code (directory structure, building, conventions etc.). The maintainer is free to make decisions on his own as long as they do not affect other projects and do not conflict with the WebIssues philosophy.
+
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).
  
−
The system also has a single leader responsible for making all strategic decisions (the scope of each project, important features, technologies used), defining the release schedule and organization of the entire system. The leader also coordinates tasks which require cooperation between various projects (for example, when a change in the server affects the client). All decisions made by the leader are consulted with the entire team, but once made they are final.
+
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 ==
 
== Project Philosophy ==
  
−
WebIssues is an open source system created by volunteers and the currently available manpower is very limited. The general principle of the project is trying to achieve maximum effect with minimum effort. In order to accomplish this, several rules must be followed:
+
Below are some general design principles of WebIssues:
  
−
; Keep it simple
+
; Universality
−
: The system should consist of a large number of simple, easy to use and generic features. Avoid creating features designed for only a small group of users or making complex solutions that no one will take full advantage of and will just make using and developing harder. Try to reuse existing concepts.
+
: 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.
−
; Keep it backward compatible
+
; Usability
−
: Adding a new field to the WebIssues protocol may be tempting but will force all users to install a new version of the client. It means that only new commands can be added to the protocol and existing ones must not be changed except for major versions (see [[./Protocol|protocol description]] for more information). Also when changing the database structure take into account that it must be possible to easily upgrade existing installations.
+
: 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.
−
; Keep it multi-platform
+
; Portability
−
: Another important rule is that WebIssues should support both Linux and Windows and several databases, currently ySQL, PostgreSQL, Firebird and SQL Server. There should be no exception for that. Features that only work in a particular environment can be offered as extensions or customizations but should never go into core releases.
+
: 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.
−
; Keep it customizable
+
; Backward compatibility
−
: The three rules mentioned above make WebIssues a general platform for creating customized solutions for particular purposes. If someone is willing to pay for integrating WebIssues with a lawnmower controller, we can do it, as long as we keep the required changes fully separated from the core version so that we don't have to violate any of the above rules.
+
: 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.

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.
Retrieved from "https://wiki.mimec.org/index.php?title=WebIssues/Guidelines&oldid=316"