LxCenter Coding standards

Coding standards for PHP

Coding standards for C

Repository Structure

Commit Guidelines

  • Avoid committing several unrelated changes in one go. It makes merging difficult, and also makes it harder to determine which change is the culprit if a bug crops up.
  • Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made.
  • Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small, related groups of files) with tailored commit messages.

General Coding Standard

As of our new policy in GitHub, all code for a certain bug/todo etc. must be submitted for merge in a "Pull Request". Coding Standard defines in which condition will a pull request in GitHub be accepted. A pull request in GitHub will be accepted by a Core Member when:
  • The modified code must ensure the compatibility to the original code unless prior agreed by all Core Team Members.
  • The code follows the file formatting and coding style as mentioned above.
  • The pull request pull from an appropriate issue branch as instructed in the repository structure above.
  • The pull request is pushing to the dev branch of the repository.
  • The issue the pull request intents to solve is completely solved and in production status.
  • The new files created should meet the GNU AGPL requirment and have appropriate header.
  • Each function and class contains the appropriate comments.
  • The commits are with appropriate commit message.
    A pull request must approved by a Core Member before merging, and if one Core Member submit a pull request, another has to approve it in order to merge it to the repository.

GNU AGPL Policy and File Header

In order to comply to the GNU AGPL policy, any new files should contains the below phrase as the code comment at the beginning:
  • For HyperVM:
    HyperVM, Server Virtualization GUI for OpenVZ and Xen
    
    Copyright (C) 2000-2009 LxLabs
    Copyright (C) 2009-2011 LxCenter
    
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as
    published by the Free Software Foundation, either version 3 of the
    License, or (at your option) any later version.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.
    
    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  • For Kloxo:
    Kloxo, Web Hosting Controlpanel
    
    Copyright (C) 2000-2009 LxLabs
    Copyright (C) 2009-2012 LxCenter
    
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as
    published by the Free Software Foundation, either version 3 of the
    License, or (at your option) any later version.
    
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.
    
    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

    All files edited that originally does not contain the above string must be added be above required string.

In addition to that, every file should contain the following details before the copyright notice:

{file_name}
{file_description}

where ”{file_name}” is the name of the file, for example, template.php, and ”{file_description}” is a short description describing the usage of that file.

Example

For example, the header of a PHP file of Kloxo should contain the following:

/*
somefile.php
This file is used to deal with something.

Kloxo, Web Hosting Controlpanel

Copyright (C) 2000-2009 LxLabs
Copyright (C) 2009-2012 LxCenter

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

Function/Class Comment

Each function and Class must contain appropriate information in comment form of the code as listed below:

{name}

{description}

@todo {todo}
@param {param}
@return {return}
@throw {exception}
@author {author}

where ”{name}” is the name of function/class, for example, Auth1 Class (when the class's name is “Auth1), and Auth1 Function (when the function's name is “Auth1”), ”{description}” is the short description describing the usage of the class or function, ”{todo}” is any todo on the function that requires follow-up, ”{param}” is any variable defined in the class or function along with its usage, ”{return}” is the variable returned of a function (which is not required for classes), ”{exception}” is the exception thrown along with the case when such an exception will be thrown and ”{author}” is the contributor's name and his email, for example, “Somebody <>”. Please be noted that there can be more than one {todo}, {param}, {exception} and {author}, but each of them must follow the format above.

Example

For example, the comments for a PHP class named SomeProcess should be as follows:

/*
SomeProcess Class

The SomeProcess Class handle some processes of something.

@todo to cleanup the code
@param $something refers to the string provided
@return $return
@throw LxSomeProcessException when something happened
@author Somebody <somebody@lxcenter.org>
*/

Format of Comments

Comment of a code is the stuff that will not be executed and act as a medium to deliver a certain message for further development. For any comments of more than one line, it should use:

/* for the top and;
*/ for the bottom

This will work for both PHP and C and save the most time.

For the comments of only one line, it should use:

//

before each line. Again, this will work for both PHP and C.

Commit Message

Commit messages are required to be accompany with a issue id, as follows:

{explanation} (#{issue id}).

where ”{issue id}” should be the issue's id as appeared in the bug tracker and ”{explanation} should be the short description of the action taken in the code.

If an acknowledgement is needed, it is be as follows

{explanation} (#{issue id}). (Thanks to {contributor})

where in addition ”{contributor}” should be the name of contributors.

Loading Coding Style settings into PHPStorm IDE

  1. Copy LxCenter.xml file into the following directory:
    - "<user_home>/.WebIde10/config/codestyles" (Windows, Linux)
    - "/Users/<username>/Library/Preferences/WebIDE10" (Mac OS)
  2. Run PHPStorm IDE
  3. Press Ctrl+Alt+S to open Settings dialog
  4. Click on "Code Style" and choose "LxCenter" from Schema name drop-down

Development Cycle

A development cycle is as follows:

  1. The developer fork a new issue branch from his dev branch, where dev branch should be a fork of the dev branch of the repository lxcenter/Kloxo (for Kloxo) and lxcenter/hypervm (for HyperVM).
  2. The developer do his own development work at the issue branch and commit to that issue branch.
  3. The developer test his issue branch in his own server or virtual machine.
  4. The developer solved the problems and confirmed that branch's code can be used for production usage.
  5. The developer submit a “Pull Request”: from {developer}/kloxo/{issue branch} or bugfix to lxcenter/kloxo/dev (for Kloxo) and from {developer}/hypervm/{issue branch} or bugfix to lxcenter/hypervm/dev (for HyperVM)
  6. One or several members of Core Team review the code and approve when coding standard are matched and the code is written with high quality. If the issue is complex or difficult to understand, a good documentation with explanations and examples would help to have a pull request approval. A Core Member cannot approve his own pull request, another Core Member is required for approval.
  7. Sometimes Core Members bring out concerns and the developer edit his pull request to fulfill their requirement.
  8. A issue is solved.

Last Modified: 14 January 2011

LxCenter.xml Magnifier - PHPStorm Code Style Settings (4.04 KB) Martin Sefcik, 07/31/2010 12:41 PM