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

PHP

コーディングスタイル

バージョン5.7以降、concrete5はPHPフレームワーク・インターオペラビリティグループによるPSR-2コーディング規約を採用しました。この規約には、スペースかタブか、ブレースの位置、メソッドの命名などの多くの規定が含まれています。ぜひご一読ください。

困難な決定

生活の多くの事柄と同じように、コーディング規約はとてもパーソナルなものでもあります。無用な議論を避けるため具体的な部分は想像にお任せしますが、個人的にはこの規約のいくつかの決定にはとても失望しました。しかし、多くの良い面もあり、何よりエコシステムにとって標準規約の採用はメリットがあります。そのため、我慢して受け容れることにします。

さて、我々は同じ船の船員です！ヨーソロ！

ファイルの命名規則と保存場所

バージョン5.7以降では、concrete5はPHPフレームワーク・インターオペラビリティグループによるPSR-4標準規則をカスタマイズして採用しています。concrete5のビルトインオートローダーは自動的にクラスを探しシステムに読み込みます。

全てのコアライブラリーはPSR-4に準拠します。具体的には、Pageクラスを例にすると、名前空間付きのコアライブラリーである

\Concrete\Core\Page\Page

クラスは、下記の位置にあります。

concrete/src/Page/Page.php

PSR-4はプロジェクトごとに異なる名前空間プリフィクスを任意の開始ディレクトリに関連づけることができます。それが、我々の取った方法です。

コアソースディレクトリに依存するコードを書く際は、必ずPSR-4にそのまましたがってください。クラスは大文字で始まる、などです。

カスタマイズ

src/ ディレクトリにないクラス（ブロックコントローラー、属性コントローラーなど）は、PSR-4と同様に大文字で始めるなどのルールがありますが、ファイル名はconcrete5のクラシックな小文字+アンダースコア方式になります。これらのファイル名はキャメルケースに変換されクラス名と対応します。

具体的には、例えばブロックディレクトリとその内容は、concrete5バージョン5.6までと変化はありません。ページリストブロックのコントローラーはこれまでと同様の位置にあります。

concrete/blocks/page_list/controller.php

もしPSR-4に厳格にしたがうと、クラス名はこのようになるべきです。

controller

そして、名前空間はこうなります

\Concrete\Block\page_list

これではあまり美しくありませんし、別の問題も引き起こします。そのため、我々は次のクラスがリクエストされたとき、

\Concrete\Block\PageList\Controller

先に次のクラスがあるかどうかをチェックし…（デフォルトのPSR-4オートロードの仕様です）

concrete/blocks/PageList/Controller.php

存在しなければ、我々独自の方法で、バックスラッシュはディレクトリセパレーターに、キャメルケースはアンダースコアに変換します。

concrete/blocks/page_list/controller.php

以上が、concrete5バージョン5.7でライブラリー以外のクラスの取り扱い方になります。

既存のコード

我々はファイルの移動と命名・ディレクトリ規則の更新を注意深く行ないました。コーディング規約（スペースかタブか、ブレース、その他…）のためには、既存のコアコードをさらに修正する必要があります。優先度は低いですが、プルリクエストを送っていただければ歓迎します。

重要なお願い

コードのクリーンナップのプルリクエストを送る際は、プルリクエストを吟味するため、１つのファイルごとにリクエストを送ってください。concrete5全体のソースをクリーンナップツールを使って書き換えて送らないようにしてください。その方法であれば、我々でもできます ;-)

JavaScript

コーディング規約

JavaScriptは次の修正を加えた Airbnb JavaScript Style Guide に準じます。

  • 既存のコアコードとツールの整合性と一貫性のために、インデントのために4つのスペースを使用してください。
  • "this" を参照する際は "my" を "_this" の代わりに使用してください。

ファイルの命名規則と保存場所

JavaScriptファイルはすべて小文字とダッシュを使用し、その他のアルファベット・数字以外の文字は拡張子の前で使用することはできません。

正しい

  • js/color-picker.js
  • js/core/jquery-ui.js

正しくない

  • js/ccm.whatever.js
  • js/MyFile.js
  • js/who_knows.js

JavaScriptはコアで許可されているファイル（例えば、ブロック内のview.jsファイル）以外は、 js/ ディレクトリーにのみ保存します。

既存のコード

我々のJavaScriptのスタイルは5.7で大量に改善されていますが、我々のファイルの多くは、まだクリーンアップを必要とし、私たちのJSの命名は間違いなく、現在、これらの規格をサポートしていません。必要に応じて、我々は、ファイルの名前を変更します。しかし、コードの改善のヘルプを歓迎します。

重要なお知らせ

繰り返しになりますが、コードのクリーンナップのプルリクエストを送る際は、プルリクエストを吟味するため、１つのファイルごとにリクエストを送ってください。concrete5全体のソースをクリーンナップツールを使って書き換えて送らないようにしてください。その方法であれば、我々でもできます ;-)

CSS/LESS

コーディング規約

CSS/LESSはほとんど皆さんの領域に属するものだと思いますが、すべてのセレクターは小文字で、区切り文字にはダッシュを使っていただければと思います。また、コアに属するコーディングの場合は統一して 'ccm-' を接頭辞に付けてください。

ファイルの命名規則と保存場所

CSSファイルはすべて小文字とダッシュを使用し、その他のアルファベット・数字以外の文字は拡張子の前で使用することはできません。

正しい

  • css/jquery-ui.css
  • css/redactor.css
  • css/conversations.css
  • css/jquery-rating.css

正しくない

  • css/MyLib.css
  • css/_whozits.css
  • css/ccm.spellchecker.css

CSSはコアで許可されているファイル（例えば、ブロック内のview.cssファイル）以外は、 css/ ディレクトリーにのみ保存します。

既存のコード

我々のCSSは5.7でLESSファイルに移行しました。マイナーな構文の変更のためのプルリクエストは受け付けますが、我々はこれまでの全体的なクリーンナップにはかなり満足しているので、あまりにも必要としてはいません。

我々のCSSファイル名の中には、明らかに規約を外れているものもありますが、必要に応じて、我々はファイルの名前を変更します。コアのファイル名を変更するプルリクエストを送らないでください。

重要なお知らせ

繰り返しになりますが、コードのクリーンナップのプルリクエストを送る際は、プルリクエストを吟味するため、１つのファイルごとにリクエストを送ってください。

さらなる議論

これらの決定は軽いものではありませんし、誰かに取っては受け容れがたいものかもしれません（それはコア開発者であっても…おっと、ここまでにしておきましょう）。しかし、これらの変更はconcrete5のソースコードをよりクリーンで統一されたものに導いてくれることでしょう。

この件に関するさらなる議論は、Documentation Forum に投稿してください。

原文：Coding Style Guidelines