ゼロプロ～Season2【プロジェクト開発の準備編：2-1-4】コードのドキュメント化とコメントの書き方

プログラミングにおいて、コードの「読みやすさ」や「保守性」は非常に重要です。そのために欠かせないのがコードのドキュメント化とコメントの書き方です。本記事では、初心者でもすぐに実践できる方法を、図や具体例を交えながら解説します。

コードのドキュメント化とは？
1. ドキュメント化が重要な理由
コメントを書くときに使える基本記号
1. # を使った単一行コメント
2. ''' または """ を使った複数行コメント（ドキュストリング）
コメントの書き方
1. コメントの基本ルール
2. コメントの種類
コードのドキュメント化の手順
1. 1. ドキュメントの対象を決める
2. 2. ドキュストリングを活用する
コメントとドキュメントの具体例
1. 1. 関数のドキュメント化
2. 2. クラスのドキュメント化
コメントとドキュメントのポイントまとめ
まとめ

コードのドキュメント化とは？

コードのドキュメント化とは、コードの目的や使い方、動作の仕組みを他の人（または未来の自分）に分かりやすく伝えるための記述です。

ドキュメント化が重要な理由

コードの理解がしやすくなる
チーム開発での円滑なコミュニケーション
長期間放置したコードの保守が容易

コメントを書くときに使える基本記号

Pythonでは以下の記号を使ってコメントを記述します。

# を使った単一行コメント

1行のコードに説明を加える場合に使用します。

x = 10  # 初期値を設定

''' または """ を使った複数行コメント（ドキュストリング）

複数行のコメントや関数の説明を記述します。

def example_function():
    """
    この関数は単純な例です。
    必要に応じて複数行にわたり説明を記載できます。
    """
    pass

コメントの書き方

コメントの基本ルール

良いコメントとは、必要最小限でありながら、コードの意図や動作を簡潔に伝えるものです。以下のポイントを意識しましょう。

コードの内容をそのまま繰り返さない
「なぜ」そのコードを書いたのかを説明する
関数やクラスの目的を明記する

良いコメントの例

# ユーザーから入力を受け取り、数値に変換する
try:
    user_input = int(input("数値を入力してください: "))
except ValueError:
    print("無効な入力です。数値を入力してください。")

悪いコメントの例

# 変数に入力を格納
user_input = int(input("数値を入力してください: "))

コメントの種類

1. インラインコメント

1行のコードに対して説明を書く場合に使用します。

x = 10  # 初期値として10を設定

2. ブロックコメント

複数行にわたるコードの説明を書く場合に使用します。

# 以下のコードは配列をソートし、
# 重複する要素を削除した新しいリストを生成します。
unique_sorted_list = sorted(set(original_list))

3. ドキュストリング（Docstring）

関数やクラス、モジュールの説明を書くためのコメント形式です。

def add_numbers(a, b):
    """
    2つの数値を受け取り、その合計を返します。

    Args:
        a (int): 1つ目の数値（例: 加算対象の値）
        b (int): 2つ目の数値（例: 加算対象の値）

    Returns:
        int: 2つの数値の合計（例: a + b の結果）
    """
    return a + b

コードのドキュメント化の手順

1. ドキュメントの対象を決める

以下の要素にドキュメントを追加するのが一般的です。

関数: どんな動作をするのか？引数や戻り値は？
クラス: クラスの目的や使用方法
モジュール: ファイル全体の概要

2. ドキュストリングを活用する

Pythonではドキュストリングを活用することで、関数やクラスの仕様を分かりやすく記述できます。

ドキュストリングのテンプレート

def function_name(param1, param2):
    """
    関数の目的を簡潔に記述します。

    Args:
        param1 (type): 説明
        param2 (type): 説明

    Returns:
        type: 説明
    """
    # コードの処理

コメントとドキュメントの具体例

1. 関数のドキュメント化

def calculate_area(length, width):
    """
    長方形の面積を計算します。

    Args:
        length (float): 長方形の長さ（例: 5.0）
        width (float): 長方形の幅（例: 3.0）

    Returns:
        float: 長方形の面積（例: 15.0）
    """
    return length * width

2. クラスのドキュメント化

class Rectangle:
    """
    長方形を表すクラス。

    Attributes:
        length (float): 長方形の長さ（例: 5.0）
        width (float): 長方形の幅（例: 3.0）
    """
    def __init__(self, length, width):
        self.length = length
        self.width = width

    def area(self):
        """
        長方形の面積を計算します。

        Returns:
            float: 面積の値（例: 15.0）
        """
        return self.length * self.width

コメントとドキュメントのポイントまとめ

要素	目的	使用例
インライン	単一行のコードの説明	`x = 10 # 初期値`
ブロック	複数行の説明	複雑な処理の前に挿入する
ドキュストリング	関数・クラスの説明	関数やクラス冒頭に記述

まとめ

コメントはシンプルかつ明確に記述することが大切です。
ドキュストリングを活用し、関数やクラスに明確な説明を追加しましょう。
保守性を考慮して、「なぜそのコードを書いたのか」を記録する習慣をつけることが重要です。

次回は「Webアプリケーションの基礎」について、HTMLやCSSを用いた基本的なWebページの構築方法を解説します！お楽しみに！