Python でコメントを記述してクリーンで読みやすいコードを作成する方法

Python で適切なコメントを書くと、他の開発者やテスターがコードを簡単に読んで理解できるようになります。

一貫した構文、わかりやすい変数名、インデントを備えたクリーンなコードは、最初の本と同様で、理解しやすく、保守しやすくなっています。

さらに、最近では、個人がアプリケーションまたはソフトウェア全体の完全なコードを書くことはあまり一般的ではなくなりました。むしろ、チームまたは人々のグループが同じ目標に向かって努力することになります。この場合、クリーンで読みやすいコードにより、コラボレーションがよりシンプルかつ効率的になります。

開発者とテスターは常に、バグのないソフトウェアを実稼働環境に導入することを目指しています。クリーンで読みやすいコードを作成すると、デバッグがより簡単かつ正確になり、このプロセスが加速されます。本番環境ではいくつかのエラーが見つかりますが、よりクリーンなコードのほうが更新が簡単です。

さらに重要なことは、コードは時間が経っても新鮮なままであるため、クリーンで読みやすいコードは長く存続します。

最後に、長持ちするソフトウェアを作成するには、クリーンで読みやすいコードを用意することが重要です。しかし問題は、それを正確にどのように達成するかということです。そうですね、1 つの方法はコメントを使用することです。

プログラミング言語におけるコメントの役割

複雑なロジックのコード全体を作成したのに、次の日には中断したところから再開できないとイライラしませんか?コメントを追加するとこのようなことは起こりません。

コメントは、ソース コードが何を行っているかを説明する人間の言語です。任意の言語で作成できますが、英語は世界共通の言語であるため、できれば英語で作成してください。

そのため、数日後、場合によっては数年後にソース コードに戻ると、コメントによってかつて書いた内容が説明されます。

また、他の開発者がコードを簡単に理解するのにも役立ちます。そのため、コメント付きで記述されたコードは、作成者がいなくても永久に残ります。

さらに、異なるプログラミング言語を扱うとき、特にチームで作業しているとき、競合が発生することはよくあります。そこで役立つのがコメントです。チームメイトが書いたソース コードのプログラミング言語はわかりませんが、コメントはその背後にあるロジックを理解するのに役立ちます。

コード ドキュメントは、ソース コードを管理するためのより包括的な方法であり、チームがシームレスに共同作業できるようにします。デザイン、機能、アーキテクチャ、コンポーネントなど、コードに関するすべてが含まれています。

コメントはこのコードのドキュメントにも貢献します。適切に書かれたコメントはコードのドキュメントに直接取り込むことができるため、開発者はコードの内容とその理由だけでなく、コードの方法も理解できます。

コメントによってコードの可読性はどのように向上するのでしょうか?

• コメントはコードを読み上げるだけでなく、各行の背後にある開発者の意図を理解するのにも役立ちます。したがって、将来バグが見つかった場合でも、コードを正確に更新する場所がわかります。
• コード全体の段落としてコメントを書くことも、各コード ブロックの動作を説明する個々の行としてコメントを書くこともできます。こうすることで、あなたや他の開発者がコードをよく理解できるようになり、読みやすさが向上します。
• コメントによりコードを論理セクションに分割できるため、コードのナビゲーションが簡単になります。
• テスターがコードを読めるように、予想される入力、出力、使用例を詳しく説明するコメントを含める必要があります。
• 最後に、ドキュメントに適切に記述されたコメントを追加すると、コード ドキュメント全体の読みやすさが向上します。

Python でコメントを書くには?

Python のコメントはハッシュ (#) 記号で始まります。したがって、行をハッシュ (#) で始めると、その行に書かれた内容はすべてコメントとして扱われます。

コードを実行すると、コンパイラはハッシュ (#) で始まる行を、存在しないかのように無視します。ただし、コメントはその目的を果たすためにソース コード内に表示されたままになります。

さまざまな種類の Python コメント

主に 3 つのタイプがあります。

#1. 一行コメント

これらは上で見たものです。これらはハッシュ (#) 記号で始まります。基本的に、ハッシュ (#) 記号で始まる行はコメント専用です。したがって、これは単一行コメントと呼ばれ、ハッシュ (#) で始まる 1 行のみコメントを書くことができます。

一行コメントを書く方法は次のとおりです。

 # This is single line comment. 

#2. 複数行のコメント

技術的には、Python は複数行のコメントをサポートしていませんが、Python でこれを実現する方法があります。

ハッシュ (#) を使用して複数行のコメントを記述することもできます。ここで記述するすべての行はハッシュ (#) 記号で始まる必要があります。

 # This is the first comment.
# This is second comment.
# This is the last comment. 

#3. Python のドキュメント文字列

複数行のコメントを記述する一般的な方法は、文字列リテラル「””….””」を使用することです。三重引用符の間に何かを記述すると、Python コンパイラーはそれらの行を無視し、ファイル内の残りの部分を実行します。

これらのコメントは、関数、モジュール、クラスの直後に記述される場合、docstring と呼ばれます。

これを行うための構文は次のとおりです

""" Multi-line comments using docstrings 
in Python. """

Python でコメントを書くためのベスト プラクティス

明確で詳細なコメントを書くと、コードの可読性とメンテナンス性が向上します。そこで、Python で明確にコメントするためのベスト プラクティスを紹介します。

コメントはコードの動作を説明するだけでなく、各行の背後にある目的と意図を反映する必要があります。

古いコメントを削除し、コードを変更するたびにコメントを更新してください。

長い話ではなく、短く要点を絞ったコメントを書きましょう。

 Bad example: The function takes a,b as input, calculates a + b, and returns the value.
Good example: The function returns the sum of a and b.

変数名と関数名に意味のあるわかりやすい名前を使用すると、冗長なコメントを排除できます。

コードが先ですか?それとも最初にコメントしますか？コーディング前にコメントすることがベスト プラクティスです。つまり、コメントを記述してから、対応するコードを記述します。このようにして、最初にロジックを考えてから、それをコードに変換できます。

 # Returns true if the cnt is less than 1.
return cnt < 1

コード全体で、スペース、インデント、コメントの種類などの一貫したコメント形式を使用します。これにより、読者にとって混乱が少なくなり、より整理されたものになります。

次の例に示すように、docstring を使用して Python の関数とクラスを説明します。

 def add_num(a,b):
    """ this function returns the sum of a and b """
    sum = a+b
    return sum

コード内で不必要なコメントを避けてください。たとえば、次のコード行を理解するのにコメントは必要ありません。

 ans = 42

コメント管理に最適なコードエディタ

#1. Visual Studioコードエディター

Visual Studio Code Editor は、 完全な開発環境のために Microsoft が構築した最高の IDE です。 Node.js と JavaScript のネイティブ サポートにより、このツールは他の多くのプログラミング言語もシームレスにサポートします。

この高度にカスタマイズ可能なツールには、さまざまな機能用のさまざまな拡張機能があります。 「Better Comments」は、人間に優しいコメントを作成できる拡張機能の 1 つです。

コメントをアラート、クエリ、ハイライトなどに分類して、ナビゲーションを容易にすることができます。

VS コードはマルチカーソル編集をサポートしているため、複数行を同時にコメントしたり編集したりできます。

このエディタは、Mac、Windows、Linux などのすべての主要なプラットフォームで利用できます。

#2. 崇高なテキスト

Sublime Text は、 大規模なプロジェクトや大量のコーディングに最適なエディターです。このエディタは、その速度、カスタマイズ、ショートカットで知られています。

このツールの強力な構文強調表示機能を使用すると、コードとコメントを簡単に区別できます。

VS コードと同様に、Sublime text も複数の行を同時にコメントするためのマルチカーソル編集をサポートしています。

オートコンプリート機能のおかげで。コード行を手動で繰り返す必要はありません。この機能はパターンに基づいてコードを自動補完するため、コードをより速く作成できます。

さらに、このツールの「Goto Anything」機能を使用すると、プロジェクトの機能とファイルをシームレスに切り替えることができます。

#3. メモ帳++

Nodepad++ は、 C++ で書かれた人気のあるシンプルなテキスト エディターであり、多数のプログラミング言語をサポートしています。 VS Code や Sublime Text のような最新のエディターのようには見えません。そのインターフェースは非常に単純で、必要なことを実行しているように見えます。

Nodepad++ には、効率的にコメントを作成するための標準ショートカットが数多く用意されています。ショートカット キーボードをカスタマイズして、コメント エクスペリエンスをカスタマイズすることもできます。

ドキュメント マップ機能によりプロジェクト構造の概要が表示され、ファイル、フォルダー、コードをシームレスに移動できます。

#4. ヴィム

Vim IDE は、より迅速な開発とコード実行を提供します。このエディターではキーボード ショートカットを使用してあらゆる操作を行うことができるため、使いこなすには真剣な努力を払う必要があります。

このキーボード中心のエディターは、キーボード ショートカットによる多くのコメント機能も提供します。コメント内を効果的に移動するための強力な機能とコマンドが備わっています。

この軽量のソフトウェアは、巨大なファイルと何百ものプログラミング言語を処理できます。無料のものを嫌う人がいるでしょうか？リスト内のすべてのエディターと同様、Vim も完全に無料でオープンソースです。

macOS および Linux システムにはネイティブで提供されており、Windows ではダウンロードできます。

#5. PyCharm

PyCharm は 、Python 開発用に特別に設計された強力な IDE です。他の多くのプログラミング言語もサポートしていますが、Python で最もよく機能します。コード補完、構文ハイライト、Python に合わせたデバッグ機能が備わっています。

さらに、Python でのコメントの効率が大幅に向上します。特定のコメントに簡単にジャンプできるナビゲーション機能を提供します。

さまざまなコメント テンプレートを取得し、Pycharm でカスタム コメント テンプレートを効率的に作成します。

また、エディターのリファクタリング ツールを使用すると、コメントを簡単に更新または修正できます。

結論

コード標準に従うことは、コード開発プロセス全体を通じて必要であり、コードは他のすべての開発者やテスターが読み取れる必要があるため、実稼働対応のコードを作成するために必須です。

読みやすいコードを作成するための重要な習慣の 1 つは、コメントを書くことです。コメントは、ほぼすべてのプログラミング言語で使用できます。ただし、この記事では、Python コメントの書き方、その種類、コメントを書く際に従うべきベスト プラクティスを理解できるようになりました。

また、コメント管理に役立つ最高のコード エディターもリストに記載されています。