From xoopscube

Contents 1 コーディングスタイル ガイド 1.1 命名規則（Naming Convention） 1.2 名前空間（Namespace） 1.3 クラス（Class） 1.3.1 命名規則（Naming Convention） 1.3.2 コンストラクタ（Constructor） 1.3.3 初期化（Initialize） 1.3.4 Private case 1.3.5 Object case 1.4 Access Level 1.4.1 Class 1.4.2 Member 1.4.3 Read Only Property 1.5 Local Variables 1.5.1 Naming Convention 1.5.2 Initialization 1.6 Code 1.6.1 Comparison Operation 1.7 Misc 1.7.1 Class Driven 1.7.2 Global Function 1.7.3 Document System

コーディングスタイル ガイド

この文書は私たちがどのように XOOPS Cube のコードを書いているかのガイドラインです。いくつかのメモをのせています。

• 現存するいくつかのファイルは、このガイドラインに従っていません。
• すべてのファイルはこのガイドラインに沿うように改善されています。
• モジュール開発者は、かならずしもこのガイドラインに沿う必要はありません。XCube のガイドラインは、通常の PHP のコーディングスタイルとは異なっているからです。

命名規則（Naming Convention）

名前空間	Pascal	XCube, Legacy, User, FoonyD
クラス	Pascal	Object, Controller, ObjectHandler
抽象クラス	'Abstract' + {Class}	AbstractAction, AbstractObject
クラスの実体名	{Namespace} + '_' + {Class}	Legacy_ObjectHandler
メンバ変数	m + Pascal (or) '_m' + Pascal	$mName, $mHandler, $mRealName
メゾット	camel	execute(), getName(), convertFromIntToFloat()
秘匿メゾット	_ + camel	_notifyRemove(), _getInnerStatus()
デリゲート	m + Pascal	getObject() --> $mGetObject
method parameter	camel	function bar(&$obj, $isForce);
ローカル変数	camel (or) {prefix} + '_' + camel	$name, $showFlag, $t_nameList

名前空間（Namespace）

名前空間の概念についてはしっかりとしておかねばなりません。（しかし）PHP は仕様上、名前空間を提供しませんので、接頭辞をつかって、名前空間を構築します。
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.
名前空間の命名規則は Pascal（最初の一文字が大文字になります）です。

XCube_XXXXXX
Legacy_XXXXXX
User_XXXXXX

クラス（Class）

命名規則（Naming Convention）

A name of classes is Pascal format. The first letter has to be big letter.
クラスの命名規則は Pascal（最初の一文字が大文字になります）です。

XXXXXX_Article
XXXXXX_Data
XXXXXX_DataHandler

A name of methods is Camel format. The first letter has to be small letter.
メゾットの命名規則は camel（最初の一文字が小文字でなければなりません）です。

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

A name of member properties is Pascal with prefix 'm'.
メンバ変数の命名規則は、接頭辞 'm' を付けた Pascal です。

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

You may use '_m' prefix to warn its access level or its access rules.
'_m' を接頭辞とすることで、そのメンバ変数のアクセスレベルとアクセスルールについて注意を喚起することもできます。

var $_mName;
var $_mLoadedFlag;

コンストラクタ（Constructor）

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 ....
    }
  }

初期化（Initialize）

• Initialize primitive member properties in the same time as definition.
• Initialize object member properies in the constructor.

• 定義するときに同時に、（プリミティブな）メンバ変数を初期化するようにしてください。
• コンストラクタで、オブジェクトのメンバ変数を初期化するようにしてください。

Private case

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

Object case

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

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

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

Access Level

Doxygen style. But, all entities don't need to have Doxygen style comments, because only APIs should have comments.

Class

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.
• Under @internal class, all of members are internal without the specific access level. And, internal class is not public APIs for outside.
• Even if the class is @public, outside programs don't use @internal entities.

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

 /**
  * @public
  * @internal
  */
 class MyModule_EditAction
 {
   ...
 }

MyModule_EditAction is public. But outside programs of MyModule should not use this class.

Member

 /**
  @protected
  */
 var $mName;

 /**
  @private
  */
 var $_mLoadedFlag;

Private members should be started with '_'. But if it is members of @internal classes, that is not must. And, members starting with '_' are used as special members for the specific class. In this case, Doxygen comment @brief should have [Secret Agreement] as prefix. And, adds the description to @attention.

 /**
  * @public
  * @brief [Secret Agreement] string - Used for a cache of results.
  * @attention
  *     Only the xxx manager should access this property.
  */
  var $_mResults;

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

Read Only Property

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

  class Foo
  {
    /**
     @public
     @brief [READ ONLY] FooManager
     */
    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);

Local Variables

Naming Convention

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.

Initialization

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 before first using $out.

$out = null;  //< initialization

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

print $out;

Code

Comparison Operation

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");
  }

Misc

Class Driven

All of logic should be contained to some class.

Global Function

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

Document System

XOOP Cube recommend not PHPDoc but Doxygen.