Zen

このエントリでは WebModule の考え方と、モジュールを実装する際のポリシーについて説明します。

WebModule の考え方

WebModule は、コンパクトで品質が保証されているモジュールを沢山用意することで、 部品の利用率を高めるというスタイルを推奨しています。

このような考え方は、
UNIX では「一つのことを行い、またそれをうまくやるプログラムであるべき」「協調して動くプログラムであるべき」と表現され、
"Zen of Python"(日本語訳) においても、以下の言葉で表現されています。

• Beautiful is better than ugly. (醜さよりも美しさ)
• Explicit is better than implicit. (不言実行よりも有言実行)
• Simple is better than complex. (複雑よりもシンプル)
• Complex is better than complicated. (入り組んだ１行よりも、複数行のコード)
• Flat is better than nested. (深い階層よりも平坦な階層)
• Sparse is better than dense. (過密なコードよりも疎なコード)
• Readability counts. (読みやすさに勝るものなし)
• If the implementation is hard to explain, it's a bad idea. (説明が大変なら、それは悪いアイディアだ)
• If the implementation is easy to explain, it may be a good idea. (説明が簡単なら、それはいいアイディアだろう)

Policy

WebModule では、以下のようなモジュールの設計と実装の目安があります。

• 1 つのモジュールに 1 つのクラスが基本です

  • Spec.js のように複数のクラスを Export する事も可能です

• 1 つのクラスは 200〜400行程度の適切なボリュームで実装してください

  • 大きくなりそうな場合は、分割を検討してください
  • あまりに行数が多いと npm run score のメンテナンス性の評点が下がります

• テストが可能なように実装してください

  • テストが存在しない。テストが行われていないモジュールは使用しないでください

• モジュールの作者は、静的解析(カバレッジ)を突破し、一定の品質があることを証明してください

  • 1 つのクラスにメソッドを10個以上持たせないでください。恐らく複雑すぎます。分割してください

• どこでも動き、誰でも、どこからでも利用されるモジュールを目指してください

  • Google で検索できないモジュールは、結局誰からも利用されません
  • 隠さずに公開してください
  • ただし、ビジネスロジックは公開しないでください

• 時間がかかってもよいので、血の通った(分かりやすい)ドキュメントを書いてください

  • 良い文章を書く唯一の方法は何度も推敲することです。誰もが最初からスラスラと書けるわけではありません
  • ドキュメントを一部の人にしか見えない場所に隠さないでください

• WebModuleList にあるモジュールを参考にしてください

必ずしもこれらを守る必要はありませんが、善処をお願いします。