XOOPSCube

The new document is here. This page may be removed in the near future.

Coding Style Guide anchor.png

This article is the guideline how we write code in XOOPS Cube. Some notes are here;

  • Some of existing files doesn't follow this guideline.
  • All files are improved to follow this guidelinenow.
  • Module developers doesn't need to follow this guideline, because the guideline of XCube is different from common PHP coding style.
Page Top

Naming Convention anchor.png

NamespacePascalXCube, Legacy, User, FoonyD
ClassPascalObject, Controller, ObjectHandler
Abstract class'Abstract' + {Class}AbstractAction, AbstractObject
Real Classname{Namespace} + '_' + {Class}Legacy_ObjectHandler
member Propertym + Pascal (or) '_m' + Pascal$mName, $mHandler, $mRealName
methodcamelexecute(), getName(), convertFromIntToFloat()
hidden method_ + camel_notifyRemove(), _getInnerStatus()
delegatem + PascalgetObject() --> $mGetObject
method parametercamelfunction bar(&$obj, $isForce);
local variablescamel (or) {prefix} + '_' + camel$name, $showFlag, $t_nameList
Page Top

Namespace anchor.png

We have to keep the concept of the namespace. The PHP spec doesn't offer the namespace, so we use the prefix convention to realize the namespace.

{Namespace} _ {Class name}

Namespace format is Pascal. The first letter has to be big letter.

XCube_XXXXXX
Legacy_XXXXXX
User_XXXXXX
Page Top

Class anchor.png

Page Top

Naming convention anchor.png

A name of classes is Pascal format. The first letter has to be big letter.

XXXXXX_Article
XXXXXX_Data
XXXXXX_DataHandler

A name of methods is Camel format. The first letter has to be small letter.

function convert();
function isNew();
function getVisibleBlocks();

A name of member properties is Pascal with prefix 'm'.

var $mName;
var $mDescription;
var $mRealName;

You may use '_m' prefix to warn its access level or its access rules.

var $_mName;
var $_mLoadedFlag;
Page Top

Constructor anchor.png

A sub class has to implement the constructor and call base class' constructor at the head part of own constructor.


  class SubClass extends BaseClass
  {
    function SubClass()
    {
      parent::BaseClass();

      .... code ....
    }
  }

Page Top

Initialize anchor.png

  • Initialize primitive member properties in the same time as definition.
  • Initialize object member properies in the constructor.
Page Top
Primitive case anchor.png

  class Foo
  {
    var $mName "No name";
    var $mDescription "";
    var $mLimit 10;
    var $mChildlen = array();
  }

Page Top
Object case anchor.png

  class Foo
  {
    var $mGetObject null;
    var $mFilter null;

    function Foo()
    {
      $this->mGetObject =& new XCube_Delegate();

      $root =& XCube_Root::getSingleton();
      $this->mFilter =& $root->mFilter;
    }
  }

Page Top

Access Level anchor.png

Doxygen style.

Page Top
class anchor.png

Now, most of classes doesn't declare access level. But, this document explains the following conventions.

  • In the case where the class doesn't define the access level, its access level seems internal fot the namespace.
    • Doxygen style doesn't recognize @internal. Fot that, write @protected with [internal].
  • Under internal class, all of members are internal without the specific access level.
  • It's possible to define internal class which is a sub class of public classes.
    • That's strange! But, this convention helps developers from the imposition which forces to put access level to all of members.

/**
 * @public
 * The simple frame work.
 */
 class MyModule_ActionFrame
 {
   ...
 }

 /**
  * @protected
  * [Internal]
  */
 class MyModule_EditAction
 {
   ...
 }

Page Top
member anchor.png

 /**
  @protected
  */
 var $mName;

 /**
  @private
  */
 var $_mLoadedFlag;

Access level is allowed to unmatch with prefix expressions. But, it needs remark and [Secret Agreement].


 /**
  * @public
  * @remark Only the xxx manager should access this property.
  */
  var $_mResults;

 /**
  * @public
  * [Secret Agreement] Notify removing this object from the manager.
  * @remark Only the xxx manager should call this method.
  */
  function _notifyRemove()
  {
    ...
  }

Page Top
Read Only Property anchor.png

Basically, other classes should not access member peroperties directly. But, a class can allow to read its property with [Read Only] keyword.


  class Foo
  {
    /**
     @protected
     [READ ONLY]
     */
    var $mManager;
  }

  $fooObject =& new Foo();
  $fooObject->mManager->bar();

However, in this case, you should not write the property directly. And, the class should implement the setter method, if it allows to write.


  // BAD
  $fooObject =& new Foo();
  $fooObject->mManager =& new AnotherManager();

  // GOOD
  $fooObject =& new Foo();
  $fooObject->setManager($anotherManager);

Page Top

Local Variables anchor.png

Page Top

Naming Convention anchor.png

Local variables format is Camel. The first letter has to small letter. And, the plural words are tied without the under score.

[X] $target_name_list
[O] $targetNameList

However, some hungarian uses are allowed. In this case, add the hungarian prefix to the head of Camel.

$t_nameList

Verbal omission is bad. You can do it for only escaping conflict with reserved keywords.

Page Top

Initialization anchor.png

All local variables have to be initialized at first, even if the PHP spec doesn't requests it. For example;


if ($flag) {
  $out "OK";
}
else {
  $out "NG";
}

print $out;

This code will run correctly. But, the guideline of XCube requests the initialization code.


$out null;  //< initialization

if ($flag) {
  $out "OK";
}
else {
  $out "NG";
}

print $out;

Page Top

Code anchor.png

Page Top

Comparison Operation anchor.png

You should write comparison operations except bool values.


 // [O] case
 $flag false;
 if ($flag) {
   ...
 }

 // [X] case
 $number 3;
 if ($number) {
   ...
 }

 // [O] case
 $number 3;
 if ($number 0) {
   ...
 }

Under XCube style, 0 doesn't equal false.


  // BAD
  $count $handler->getCount();
  if (!$count) {
    die("no data");
  }

  // GOOD
  $count $handler->getCount();
  if ($count == 0) {
    die("no data");
  }

Page Top

Misc anchor.png

Page Top

Class Driven anchor.png

All of logic should be contained to some class.

Page Top

Global Function anchor.png

XOOPS Cube doesn't recommend global functions except macro like functions. Macro functions is a shortcut which mix-and-match methods.

Page Top

Document System anchor.png

XCube recommend not PHPDoc but Doxygen.


Front page   Freeze Diff Backup Copy Rename ReloadPrint View   New Page Page list Search Recent changes   Help   RSS of recent changes (RSS 1.0) RSS of recent changes (RSS 2.0) RSS of recent changes (RSS Atom) Powered by xpWiki
Counter: 20685, today: 4, yesterday: 6
Princeps date: 2007-01-19 (Fri) 00:35:05
Last-modified: 2007-06-29 (Fri) 11:48:21 (JST) (4402d) by minahito

Welcome | News | Overview | Documentation | Forum | Tutorialstop
Brasilian | French | German | Greek | Japanese | Korean | Russian | T-Chinese
Powered by XOOPS Cube 2001-2011 The XOOPS Cube Project