初心者のためのドキュメンテーションコメント入門

ドキュメンテーションコメントとは

リンクをコピーしました

ドキュメンテーションコメント（以下、Docコメント）とは、メソッドやクラスが何をするのか、どんな引数や返り値を持つのかを明記したコメントのことです。
普通のコメントが開発者向けのメモであるのに対し、Docコメントはコードの利用者・後から読む人向けの説明です。これをきちんと書くことで、コードの可読性、再利用性、保守性が向上します。

Rubyでは、YARD（Yet Another Ruby Documentation）というツールを使ってDocコメントを記述するのが一般的です。この記事ではYARD形式を中心に、基本の書き方から効率化の方法まで、具体的な例を交えて解説します。

ドキュメントコメントのメリット

リンクをコピーしました

Docコメントには以下のようなメリットがあります。

ドキュメンテーションコメントの基本構文

リンクをコピーしました

Docコメントは言語ごとに書き方が異なりますが、共通して「メソッドやクラスの仕様を体系的に記述する」という目的を持っています。今回はRubyでの例を紹介します。

RubyのDocコメントは#を使って記述します。以下はよく使うYARD形式のタグの一覧です。

実践的なDocコメント例

リンクをコピーしました

実際のDocコメントは以下のようになります。

■基本例

1
2
3
4
5
6
7
# 与えられた数値を三倍にします。

# @param value [Integer] 入力値
# @return [Integer] 三倍になった数値
def triple(value)
  value * 3
end

■複雑な例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# ユーザーの年齢から利用料金を計算する
#
# @param age [Integer] ユーザーの年齢（0以上150以下）
# @param student [Boolean] 学生かどうかのフラグ
# @return [Integer] 計算された料金（円）
# @raise [ArgumentError] 年齢が範囲外の場合
#
# @example 基本的な使用例
#   calculate_fee(20, true)  #=> 500
#   calculate_fee(30, false) #=> 1000
#
def calculate_fee(age, student = false)
  raise ArgumentError, "年齢は0以上150以下で入力してください" unless (0..150).include?(age)

  base_fee = 1000
  base_fee *= 0.5 if student
  base_fee
end

このようにDocコメントを記述しておけば、メソッドのコードを全て確認しなくても、どのようなメソッドで、どんなふうに引数を渡せば良いか簡単に確認することができます。

良い例と悪い例の比較

リンクをコピーしました

Docコメントを書く際の良い例と悪い例を比較してみましょう。

■悪い例（曖昧な説明）

1
2
3
4
# データを処理します。
def process(data)
  JSON.parse(data)
end

これだと何を処理するかわかりません。

■良い例（具体的な説明）

1
2
3
4
5
6
7
8
9
10
11
# JSON文字列をパースしてHashに変換します。

# @param data [String] JSON形式の文字列
# @return [Hash] 変換されたHash
# @raise [JSON::ParserError] パースに失敗した場合
# @example
# parse_json('{"name":"pikachu"}')
# #=> {"name" => "pikachu"}
def parse_json(data)
  JSON.parse(data)
end

これだと一目で役割・引数・戻り値がわかります。

効率的なドキュメンテーションコメントの書き方

リンクをコピーしました

このようにDocコメントは非常に有効ですが、作成するのが面倒に感じられ、省略されてしまうことも少なくありません。
ですが以下の方法で効率的に作成することができます。

1. テンプレートを用意する

リンクをコピーしました

毎回ゼロから書くのではなく、テンプレートを用意しておくと便利です。こうすることでチーム全体でDocコメントの品質を均一に保つことができるというメリットもあります。

1
2
3
4
5
6
7
# [メソッドの説明]
#
# @param [型] 変数名 [引数の説明]
# @return [型] [戻り値の説明]
def my_method(arg1)
  # ...
end

このようなテンプレートをプロジェクト内で共有することで、誰が書いても同じフォーマットでドキュメントが生成されます。

2. 生成AIを使った方法

リンクをコピーしました

生成AIを使って効率的にDocコメントを作成することもできます。
PikawakaではGitHub Copilotを使ったDocコメントの作成の仕方などが学べるカリキュラムを用意しています。
詳しくはこちらをご覧ください。

まとめ

リンクをコピーしました

ドキュメンテーションコメントは、単なるコードの補足ではなく、コードの意図を正確に伝えるための重要な要素です。これを丁寧に記述することで、コードの理解や保守が格段に容易になり、結果としてチーム全体の生産性の向上につながります。

この記事を参考に、ぜひご自身のプロジェクトにもドキュメンテーションコメントを導入してみましょう。

役に立ったらSHARE♪

• twitter
• facebook
• はてブ