[初心者向け] ソースコードのコメントの書き方

ソースコードのコメントは、コードの可読性や保守性を向上するために必要です。
コメントの書き方について紹介します。

やすひら

ソースコードのコメントの書き方を紹介します

本記事では、Pythonでのコメントを例にコメント方法を紹介します。

コメントとは

コメントとは、コードに記述する説明文やメモのことです。
コメントを入力しても、プログラムの動作には直接影響せず、ソースコードを読む際の理解度を向上させるのに利用できる機能です。
コメントを入れるメリットを紹介します。

可読性向上

ソースコード上の処理の意図や流れがわかりやすくなります。
プログラミングは、複数人で作業することが多く、他のエンジニアが見てもわかるようにすることが、コメントを書く際に重要になります。
また、未来の自分が見た際に、処理を忘れていることがあるため、未来の自分が理解しやすくなるメリットもあります。

保守性向上

複雑な処理や特定の実装の理由を明記しておくことで、処理を入れた経緯がわかりやるくなり、処理を変更しやすくなります。

デバッグ/ログ解析しやすくなる

プログラムの動作時やテスト時にエラーが発生した際に、どの部分に問題があるかをコメントを元に解析しやすくなります。

過剰なコメントや不要なコメントは、ソースコード上の読み込む量が多くなり、逆に見づらくなります。
適度で適切な内容を、コメントとして残すことが重要です。

あわせて読みたい

[初心者向け]デバッグとは？ | デバッグの手法とコツを紹介

コメントの記載事項と書き方

コメントで記載したい内容について紹介します。

目的や意図

何を処理するためのコードかを簡潔に説明する。
オブジェクト指向でプログラミングしている場合は、クラスの概要やメソッド概要等を記述すると良いです。

ソースコード

class Tanuki:
    """ タヌキクラス: タヌキオブジェクトを生成 """
    def __init__(self, name, age):
        self.name = name # 名前
        self.age = age   # 年齢

クラスの概要や意図を記載しています。

処理の流れやロジック

ロジックやアルゴリズムの処理の流れを記述します。
上から処理を読む際に、何の処理を実行しているかを、コメントとして記述しておけば、処理の流れがわかり、デバッグやログ解析に役立ちます。

ソースコード

def greet(request):
    # 挨拶の応答を生成
    if request == "Hello": # こんにちは
        response = "Hello"
    elif request == "Good morning": # おはよう
        response == "Good morning"
    elif request == "Good evening": # こんばんは
        response == "Good evening"
    elif request == "Good night":   # おやすみ
        response == "Good night"
    else: # その他
        response == "Do you need something?"

    return response

処理の流れや判定内容についてコメントしておくと、デバッグやログ解析に役立ちます。

関数/メソッドのインプットとアウトプット

関数やメソッドを定義する際のインプット(引数:Argument)とアウトプット(戻り値:Return)をコメントとして記述しておけば、他エンジニアが関数やメソッドを利用する際に利用
しやすくなります。
また、変数の型を指定する場合は、変数型もコメントとして記述しておくと良いです。

ソースコード

def greet(request):
    """
    挨拶の応答を生成する。

    Args:
        request (str):  リクエスト

    Returns:
        response (str): レスポンス
    """

    if request == "Hello":
        response = "Hello"
    else:
        response == "Do you need something?"

    return response

関数のインプットとアウトプットをコメントしておくと、他エンジニアが関数を利用しやすくなります。

注意事項

使用する際に気をつける点や、特定の条件で動作する事項など、エンジニアが注意するべき事項を記述します。
クラスやメソッドを条件付きで利用できる場合、コメントとして注意事項を記述しておくと他のエンジニアが利用しやすくなります。

ソースコード

def greet(request):
    # 挨拶の応答を生成
    # 注意事項: LLMによる判定ではないため汎用的な応答はできない
    if request == "Hello": # こんにちは
        response = "Hello"
    elif request == "Good morning": # おはよう
        response == "Good morning"
    elif request == "Good evening": # こんばんは
        response == "Good evening"
    elif request == "Good night":   # おやすみ
        response == "Good night"
    else: # その他
        response == "Do you need something?"

    return response

関数の注意事項を記載しておくと、他エンジニアが理解しやすいです。

TODO

後日追加する予定の機能や、改善が必要な箇所を記述します。
ソースコード上にコメントを記述しておくことで、今後機能を追加する際に修正しやすくなります。

ソースコード

def profile(name, age):
    # 自己紹介分を生成
    message = f"Hello, I am {name}, I am {age} years old."

    # TODO: 自己紹介に必要な事項があれば追加していく

    return message

今後、修正が必要な事項について、修正箇所にコメントしておくことで、他エンジニアが作業しやすくなります。

まとめ

プログラミングにおけるコメントの書き方を紹介しました。

コメントを適切に記載することは、プログラムの可読性やメンテナンス性を向上させるために重要です。
読みやすいソースコードは、無駄な読み込み時間や調査時間を削減することができるため、生産性向上に役立ちます。
他のエンジニアが読みやすいかを考えながらプログラミングしていくと良いです。