こんにちは、すのくろです。
Pythonのコメントアウトは、効果的なコードの記述とメンテナンスに欠かせない重要な要素です。
この記事では、Pythonのコメントアウトの実践的な使い方とベストプラクティスを詳しく解説します。
Python コメントアウトとは？
Pythonのコメントアウトは、コード内に追加される説明的なテキストです。
これは主に、コードの目的や特定の処理の説明、後からコードを読んだりメンテナンスしたりする際のヒントを提供するために使われます。
コードに記述されたコメントは、実行時に無視されるため、プログラムの動作には影響を与えません。
コメントアウトの目的
コメントアウトの目的は主に以下になります。
- コードの目的や特定の処理の説明
- コードの一部を一時的に無効化するためのテクニック
- コードの理解やメンテナンスをサポートするためのヒント
コメントアウトを効果的に使うことで自分も他者もプログラムコードを理解しやすくなり、開発が進みます！
Python コメントアウトの書き方
Pythonでは、シングルラインコメントとマルチラインコメント (Docstrings)の2つの主要なコメントアウトの方法があります。
Docstringsもコメントの一形態といえますが、一般的なシングルコメントアウトと異なる使い方と目的があります。
コメントアウトは主にコード内での説明に使用し、Docstringsは関数やクラスのドキュメントとして使用するのが一般的です。
２種類のコメントアウトについて深掘りしていきますね！
シングルラインコメント
シングルラインコメントは、1行のコード内でコメントを記述する方法です。
コメントの先頭に「#」を付けることで、その行の残りの部分がコメントとして扱われます。
例：
x = 10 # 変数xに値を代入
y = 20 # 変数yに値を代入
result = x + y # xとyを足して結果をresultに代入特徴:
- 1行のコードに対して直接コメントを追加できるため、非常に簡単に使えます。
- コードの特定の行に対して説明を追加する場合や、一時的にコードを無効にする際に便利です。
使い分け:
- コード内の特定の行にコメントを追加したい場合に使用します。
- 一時的なメモや短い説明を付けたい場合に適しています。
- 複数行にまたがる説明を入れる必要がない場合に使われます。
マルチラインコメント （Docstrings）
マルチラインコメント「Docstrings」は、複数行にわたるコメントを記述する方法です。
3つの二重引用符（”’）または3つのシングルクォート（”””）で囲んだ部分がマルチラインコメントとして扱われます。
特徴:
- 複数行にまたがる長いコメントを追加できるため、詳細な説明やドキュメンテーションを記述するのに適しています。
- 複数行のコードブロックを一時的に無効化したり、ドキュメンテーション文字列として関数やクラスに説明を追加するのに便利です。
使い分け:
- 長いコメントを複数行にわたって記述する場合に使用します。
- ドキュメンテーション文字列（Docstrings）として関数やクラスに説明を追加する際に使われます。
例:
①：長いコメントを複数行にわたって記述
'''
このコードは2つの数値を足すための簡単なプログラムです。
xとyに値を代入して、それらを足してresultに結果を格納します。
'''
x = 10
y = 20
result = x + y
②：ドキュメンテーション文字列（Docstrings）として関数やクラスに説明を追加
class Rectangle:
"""
長方形の幅と高さを表すクラスです。
Attributes:
width (float): 長方形の幅
height (float): 長方形の高さ
Methods:
get_area(): 長方形の面積を計算して返すメソッド
"""
def __init__(self, width, height):
self.width = width
self.height = height
def get_area(self):
"""
長方形の面積を計算して返すメソッドです。
Returns:
float: 長方形の面積
"""
return self.width * self.heightこのように、マルチラインコメントは、特に関数やクラスのドキュメンテーションによく使用されます。
コメントアウトとDocstringsの実践的な活用法
シングルラインコメントアウトで引数の変更や試算に活用
シングルラインコメントは簡単にコメントを追加したり、一時的にコードを無効にして、違う式を試す際に活用します。
簡易的にコメントを無効化や一言コメントに使うってことですね！
↓の例では、
- 簡単にコメントの追加
- 「result」式の無効化と変更
をしています。
コードを書いているときはこの程度は書く必要がないと思うんですが、
時間が経って、コードを見返したときにコメントがないと、「ここではどんな処理をしているんだっけ？」となることが多いです。
なので、自分は面倒くさがらずにできるだけ、ある程度処理のかたまりごとに一言コメントを記載するようにしています！
Docstringsによりコード内で関数の使い方をチェック
↑で「関数やクラスの定義直後にDocstringsを記述することで、他の開発者が関数の使い方や目的を理解しやすくなります。」と述べましたが、記述したDocstringsは簡単にコード上でチェックできます！
例えば、JupyterNotebookなどのエディタでは、関数内で「Shift」+「tab」キーを押すと、↓のようにDocstringsなど説明文が表示できます。
これで、関数の使い方などがある程度わかります。
タグ付けコメントの活用
# TODO: ユーザー名を取得するコードを追加する
# FIXME: バグを修正する必要があるこの例では、TODOやFIXMEなどのタグ付けコメントを使って、未完了のタスクや修正が必要な箇所をコメントアウトしています。
これにより、後でタスクを追加・修正する際に便利です。
数日以上の期間で、長いコードを書いていくときはちょっとタグつけしておくとスムーズにコード開発が行えます。
適切なコメントアウトの使い分けにより、コードの保守性と可読性を向上させることができますね。
まとめ
以上、コメントアウトの活用方法をまとめました。
コメントアウトの活用方法により、コードの理解やデバッグ、メンテナンスがスムーズに行えるだけでなく、コードの品質を向上させることができます。
コメントアウトは柔軟に活用できるため、自分自身の作業スタイルやプロジェクトの要件に合わせて適切に使用してみてください！
自分はコメントアウトや見やすい・読みやすいコードの書き方のお作法は
「リーダブルコード」という書籍で初めに学びました！
もしさらに体系的にコードの書き方を学びたい方がいましたら購入を検討してみてください。
プログラミングの個人開発からチーム開発、すなわち実務をこなすことを見据えているのであれば、当たり前で基本的なことが載っているので、読むべき本だと思っています！
今回の例以外にも、Pythonは自由度が高く、豊富なライブラリがまだまだ用意されているため、様々なデータ処理や効率化に応用することができます！
さらにPythonのスキルを高めて、効率的に業務を行いたい、高度なPythonを中心としたプログラミングをより体系的に学びたいと言う方向けに、おすすめのオンラインスクールを２つ厳選して紹介していますので、こちらもよければご覧ください！
自分も一度体系的にPythonを学んだことで、一気に日々の業務や人生が変わったと感じています！
以上、ここまでお読みいただき、ありがとうございました！
コメント