プラグインをコーディングするにあたって注意すべき事項です。これらには従わなくても動くプラグインはかけますが、このページに書かれたルールに従っていると、様々なメリットがあります。

  • 他の人や将来の自分が読むときに、確認すべきことが減って、読みやすくなる
  • 推奨されていない方法は将来使えなくなる可能性がある。推奨されている方法を使えば、より長くに渡ってそのプラグインを修正せずに使える

あなたがプラグインを利用するだけだったとしても、開発するにしても、以下のルールを抑えれおけば細かいことを調べる必要が減ると思います。

コーディング規約

推奨されるコーディング規約

mikutterプラグインはRubyのコードなので、Rubyのコーディング規約に従って、読み手(あなたのプラグインを修正しようとしている人、勉強中の人、将来のあなた自身等)がスムーズに読めるように心がけると良いでしょう。

  • https://github.com/cookpad/styleguide/blob/master/ruby.ja.md Cookpad社のコーディング規約
  • https://github.com/github/rubocop-github/blob/master/STYLEGUIDE.md Github社のコーディング規約

こういったものを見て、どのコーディング規約でも一貫して言われているようなことには従い、意見が別れているような項目については自分の好みで選んでいったりすると良いと思います。 mikutterもそのようになんとなくやっているだけなので、残念ながらmikutterコーディングスタイルという明確な文書があるわけではありません。そもそもプラグインがmikutterと同じコーディング規約に従う必要はありません。

しかし、プラグインはオープンソースとなるはずなので、他の人がコントリビュートすることがあることを考えると、近年の主要なコーディングスタイルで意見が一致している項目を無視するのはやめるべきでしょう。例えばRubyを書いたことがない人がタブや4文字のスペースでインデントをしているのをたまに見ますが、前述したようなコーディング規約では全て2文字のスペースでインデントを行うことになっているので、Rubyを書く場合はこれに従ったほうが良いです。

mikutterに従うべきか

mikutterは2009年から開発しているため、時期によって微妙にコーディング規約が変わっています。よって、mikutterがやっていることが常に正しいというわけではなく、その書き方は数年前は由とされていたが今はそうではない、というものがいくつもあります。

mikutterでは、そういったものをその時の思いつきで全部直してしまうのではなく、関連するコードを直したときにコーディング規約に沿うように書き換えています。ここでいう関連するコードというのは、ファイル単位ではなくメソッド単位です。要するに、あるメソッドの一部を修正するときに、そのメソッドの他の部分がコーディング規約にそっていなければ修正する、ということです。このルールによって、古いコーディング規約と新しいコーディング規約が混在することがありますが、ほぼ全てのファイルのすべての行に影響が及ぶような規約の変更をしても、巨大なdiffが生成されて変更を追いかけづらくなることを防いでいます。

したがって、mikutter本体のコーディングに従うのではなく、前述したようなRubyで広く支持されているコーディング規約の方に従うべきです。

名付け

mikutterで名前をつける必要のあるものには、その種類によって個別の名付けのルールがあります。

プラグイン名

プラグインの名前は、Specファイルの name キーの値にあたるもので、ユーザに表示されるプラグイン名です。現状のmikutterではプラグイン名を表示しないので特に利用されていませんが、ここには人間がプラグインの名前を呼ぶときに使う正式名称をいれておきます。

ここには特に制約はありません。アルファベットの大文字や、日本語、半角スペースなどの記号も利用できます。適切な理由があれば「mikutter」という単語を含めることも可能です。また、他のプラグインと同じ名前をつけても構いません。

プラグインスラッグ

プラグインスラッグはプラグインの固有IDのようなものです。人間が見るための値ではありませんが、開発者のために、説明的な値にすることも出来ます。

名前の制約

半角小文字(a-z)と数字(0-9)、アンダースコア(_)が利用できます。これ以外の文字列は使わないでください。

  • 良い例
    • extract
    • chushutu_tab (日本語のローマ字表記だが、使ってはいけない種類の文字は使ってない)
  • 悪い例
    • Extract (大文字を使っている)
    • 抽出タブ (使ってはいけない文字(日本語)を使っている)
    • chushutu-tab (ハイフンは使ってはならない)

冗長なスラッグは避けるべきです。説明的な名前にしたい場合は、プラグイン名をそのような名前にして、プラグインスラッグはできるだけ単語数を抑えます。 Worldスラッグなどが、プラグインスラッグと同じであることを期待しており、簡潔な名前であることを前提としているためです。

  • 良い例
    • tigers
  • 悪い例
    • tigers_reply_command (説明的すぎる・スラッグは名前ではない)

そのような理由で、 mikutter という文字列を含んではいけません。 プラグインスラッグはmikutterプラグインにつけるものなので、それがmikutter向けであることは自明です。

  • 良い例
    • twitter
  • 悪い例
    • mikutter_twitter (説明的すぎる・そりゃmikutterプラグインだろ)
    • twitter_for_mikutter (説明的すぎる・そりゃmikutterプラグインだろ)

プラグインスラッグの重複について

プラグインスラッグが重複するプラグインを2つ以上同時にロードすることはできません。しかし、意図的にプラグインスラッグを重複させるテクニックもあります。ほとんど同じ用途で、同時に存在することの出来ないプラグインを同じスラッグにしておけば、同時にロードされないでしょう。

具体的には Display Requirements というプラグインが2つあって、どちらも :display_requirements というプラグインスラッグを持っています。

GitHubリポジトリ

GitHubのリポジトリ名には 特に制約はありません 。しかし、mikutterプラグインのほとんどがGitHubに公開されているため、参考となる指標を書いておきます。

リポジトリ名

デフォルトではこれがディレクトリ名となるので、プラグインスラッグと一致させると楽かもしれませんが、後述するようにプラグインをインストールするワンライナーを記述していれば、リポジトリ名はどのようなものであっても特に問題ないでしょう。

mikutterプラグインであることをわかりやすくするために、リポジトリ名を mikutter_(プラグインスラッグ) にしている人も少なくないですが、これは問題ありません。

    • twitter (mikutterプラグインであることがわからないが、禁止はされていない)
    • mikutter_twitter (リポジトリ名にはmikutterを含めて良い)
    • mikutter-plugin-twitter (リポジトリ名にはハイフンを含めて良い)

Description

GitHubリポジトリには、1行の説明を書くことが出来ます。ここにも 制約はありません が、 プラグインの名前 や、これがmikutterプラグインであることを記述しておきましょう。Descriptionに書いた内容はGitHubのWebページのタイトルやMETAタグに適切に格納されるので、検索エンジンでヒットしやすくなります。「mikutterで○○するプラグイン」を探している人は「mikutter ○○」などで検索するでしょうから、mikutterという単語は含めておいたほうが良いです。

    • mikutterでTwitterをするためのプラグイン。
    • Twitterのためのmikutterプラグインです。

インストール方法

プラグインスラッグとプラグインのrubyファイルは名前が一致している必要があるため、ユーザは毎回プラグインスラッグを確認する必要があります。この手間を減らすために、READMEには必ずプラグインをインストールするワンライナーを書いておいてください。例えば以下のような感じです。

$ mkdir -p ~/.mikutter/plugin; git clone https://github.com/toshi_a/mikutter_twitter.git twitter