Xcodeコメントの基本

これはiOS Advent Calendar 2014の12日目の記事です。

年の瀬もだんだん押しせまってきました。年末年始のお休みの後に、「あれ、このメソッドどんな目的で作ったんだっけ？こっちのメソッドとの関係はどうだったんだっけ……」など無駄に悩まないために、このあたりでソースコードのコメントを見直してみましょう。

Xcodeでのコメント

そもそもソースコードにコメントを書いた方がいいかどうかは長い議論がありまして……。

コメントによりコードの理解は深まるので、あったほうがいいという意見もありますが、コメントを書いたあとにコードを変更してしまうと、コメントとコードの内容が違ってしまい、かえってバグを生んでしまうためコメントを強制するのは害悪だ、という考え方もあります。また、適切な命名規則を守ればソースコードを読むだけで理解できるという考え方もあります。

実際には、プロジェクトのライフサイクルや、参加人数、また、アップデートの頻度などによって、コメントを書いたほうがいいのかはそれぞれの状況で決めるべきだと思います。

個人的には、iOS開発ではこんな理由からコメントがある方がいいと思っているので、最近はできるだけコードと同時にコメントを書くことにしています。

処理の流れはソースコードを見ればおっていくことができるが、ソースコードを読む前にクラスやメソッドの設計方針が簡単にわかると理解のスピードがあがる。
設計ドキュメントを作成するのはある程度時間がかかるので、アップデートサイクルの早いiOS開発では難しい。でもコメントであればソースコードと同時に書いていくことができる。
自分が書いたプロジェクトでも数週間〜数ヶ月すると個別の内容を忘れてしまうことが多い。

ただ、ソースコードの中の好きな場所に適当にコメントをいれるということにしていると、読む方もどこから見ていいのかわかりにくいし、自分でもコメントの修正をするときに、どこをなおせばいいかわかりにくくなってしまうので、appledoc形式のコメントをクラス、メソッド、重要なプロパティに書くようにしています。

appledoc形式のコメントとは

appledoc形式のコメントは、通常のコメントからちょっと進化した、特定のフォーマットで書くコメントです。

「appledocって設計ドキュメントを自動的に生成してくれるやつでしょ？もう知ってるよ」っていうかたもいらっしゃると思いますが、appledoc形式のコメントは、Xcodeのコード補完機能やQuick Helpにも対応しているので、ドキュメント自動生成以外にもいいことがたくさんあります。

この方式でコメントを入れておくと、システムのフレームワークのヘルプとほぼ同じように参照できるので、SafariやViewerで別のドキュメントをわざわざひらいたりしなくても、Xcodeだけで情報がわかるのが一番の魅力です。

クラスへのコメント

まず、クラスに関するコメントはヘッダーファイルのクラスの @interface宣言の上に記述します。 appledoc形式では、通常のコメントと少し違い、/*と/を使って記述します。こんな感じですね。

注意点などは @warning をつけて記述すると、強調表示になります。

/**
 サーバーからメッセージ情報を取得してくるクラス。
 取得したデータはTRSFeedParseHelperにひとつひとつなげて処理をしてもらいます。
 で、その処理がおわったら、MyHelperからNotifyされ、globalにNotificationをなげます。
 それをTRSItemListViewControllerでうけとり、必要ならreloadを行います。
 
 @warning
 バックグランド時の動作が不定
 */
@interface TOYMessageController : NSObject

このコメントを入れたクラスをクリックすると、画面右のQuick Helpにコメントが表示されます。

コード補完時にも表示されますし、オプションキーを押しながらクラスをクリックすると、その場でフローティング表示もできます。

メソッドへのコメント

メソッドのコメントも、/*と/を使って実装の前に記述します。

@paramをつけると引数の説明、@returnをつけて返り値の説明が追加できるので、よりわかりやすくなりますね。

/**
 fromdateからtodateまで何日あるかを返します。
 同じ日なら0を返します。
 @param fromdate この日から
 @param todate この日まで
 @return NSUInteger ２つのdateのあいだの日数
 */
- (NSInteger)dayBetween:(NSDate*)fromdate And:(NSDate*)todate{
...
}

クラスの説明と同様に、QuickHelpに引数と返り値もわかりやすく表示されます。

自動補完時やオプション＋クリックでも表示されます。

プロパティへのコメント

プロパティのコメントも同様に/*と/を使って記述しますが、///での記述も可能です。

/**
 リストのタイトルとして保持される文字列。
 表示されるタイトルとは異なります。
 起動時にはリセットする必要あり。
 */
@property (copy,nonatomic) NSString* titlename;

/// カテゴリーダイアログを表示した回数
@property (assign,nonatomic) NSUInteger latit;

これもQuickHelpや自動補完時、オプション＋クリックで表示されます。

pragma mark

新しいクラスでは、まず画面右上から表示できるメソッドリストを見てクラス全体のメソッドを確認することが多いと思いますが、その時に pragma mark - が入力されていると、メソッドがグルーピングされて見やすくなります。

また、気になる部分にはTODO:をいれておくと、メソッドリストの中に表示されて後から確認しやすくなります。

// TODO: ここの処理は不安が残るので、もう一度アーキテクチャの再構成をしてください。

Build Directive

また、ビルド前に必ず見直してほしい項目があったら、Build Directiveをいれておくのもいいでしょう。

warningで build warningが発生、errorでbuild errorが発生して、指定した文字列が表示されます。 warningまたはerrorがでるようにしておけば、必ず気づいてもらえます。

#warning "消費税の数値はビルド時に変更すること"

#error "ここの数値はダミー値なので、リリースするときに変更してください"

ドキュメントの自動生成

実はappledoc形式の一番のうりの機能は、「コメントを書くだけで設計ドキュメントが生成できるということです。

コメントに全部書いてあれば、わざわざドキュメントを生成する必要はないので、個人的には使ったことはありませんが、納品書類を増やしたい場合や、仕事した感をだすためにはとても有効だと思うので、そういう時にはオススメです。

ここでは詳しく触れませんが、appledocのgithubでヘルプを見てみてください。

htmlファイルまたはxcodeヘルプフォーマットでかきだせます。