【プログラミング教育ナビ】は、プログラミング初心者が自分に合った勉強法や教室を見つけられたり、プログラミングに特化した求人が検索できたり、SaaSの比較ができるサイトです。人気講座のある入門スクールや独学できる学習サイトを、口コミ・評判で比較してランキング形式でご紹介しています。言語から探す場所から探す条件から探すrsstwitterfacebook案件獲得できなかったら全額返金!未経験からプロのエンジニアスキルを身につけ、フリーエンジニアとして稼げるまで徹底サポート。まとめはじめにコメントはしっかり書いていますか?プログラムは書いている時間よりも、読んでいる時間のほうが長くなります。これは一般に開発期間よりも、保守・運用期間のほうが長くなるためです。このため、しっかりコメントを残して、他の人(一ヶ月後の自分も含む)のためにプログラムを解読する手がかりを残しておきましょう。通常のコメントだけでなく、ドキュメントコメントも合わせて書いておくと効果的です。この記事では、Python初心者の方向けに、ドキュメントコメントの書き方や閲覧方法、pydocによるHTML化についてお伝えしていきます。コメントを書いて、わかりやすいプログラムにしましょう。通常のコメントのおさらいまずは、通常のコメントのおさらいをしておきましょう。コメントは、次のように「#」を使って書くのでした。#コンソールに出力#print("commentout")コメントは行のどこからでも始めることができ、#から行末までがすべてコメントとして扱われます。プログラムの説明だけでなく、プログラムの一部を一時的に無効化するためにも使われます。これを「コメントアウト」といいます。それでは、次にドキュメントコメントの書き方を学びましょう。ドキュメントコメントを書いてみようドキュメントコメントとは、通常のコメントとは違い、クラスやメソッドなどのドキュメント(説明文)として扱われる特別なコメントのことです。Pythonでは、所定の位置に規定の方法で記述することでドキュメントコメントとして扱われます。yこの例のように、クラスやメソッド定義などの次の行に、単一行の場合は「”(または’)」、複数行の場合は「”””(または”’)」を使って記述します。単なる説明文だけでなく、メソッドなどの使用例も実行結果と合わせて記述しておくと、よりわかりやすいドキュメントになるでしょう。次は、このコメントを閲覧する方法についてみていきましょう。ドキュメントコメントを閲覧するドキュメントコメントは、自動的に対象の”__doc__属性”に文字列として格納されます。このため、次のように属性を介してアクセスすることができます。print(Calc.div.__doc__)12345print(Calc.__doc__)print(Calc.add.__doc__)print(Calc.sub.__doc__)print(Calc.mul.__doc__)print(Calc.div.__doc__)先程書いたコメントがそのまま出力されましたね。いえ、これだとあまり見やすいとはいえません。そこで、もうひとつの方法として「help関数」を使ってみます。次のコードを実行してみましょう。例:help(Calc)1help(Calc)クラスとメソッドのドキュメントが一覧で表示されましたね。これらの方法は、自分で書いたコードだけでなく、標準ライブラリなどにも使えます。*print(datetime.__doc__)help(datetime)ライブラリの使い方をサクッと調べたいときに、コンソールからPythonインタプリタを起動してhelp関数を使ってみるとよいでしょう。pydocでドキュメントコメントをHTML化するPythonでは、pydocというツールが提供されており、ドキュメントコメントをHTML化してブラウザで閲覧したり、ファイルとして出力したりできます。カラーリングなど見やすくする工夫がされているので、コンソールで見るよりも読みやすいでしょう。いちいちPythonインタプリタを起動してhelp関数を実行しなくても、pydocでも同じドキュメントコメントが閲覧できます。クイックリファレンスとして活用してみましょう。まとめわかりやすいコメントが書けましたか?単なる説明文だけでなく、関数やメソッドの使い方や実行結果などもドキュメントとして残しておくとよいでしょう。ドキュメントコメントはコンソールから閲覧できる他、pydocによりHTML化してブラウザで閲覧することもできます。ライブラリではAPIリファレンスのように使えるでしょう。投稿者:プログラミング教育ナビ編集部tweetプログラミングで挫折しそうなら、現役エンジニアにマンツーマンで相談してみませんか?オンラインのプログラミングスクール「TechAcademy」のメンターが対応。人気の記事まだデータがありません。【プログラミング教育ナビ】は、プログラミング初心者が自分に合った勉強法や教室を見つけられたり、プログラミングに特化した求人が検索できたり、SaaSの比較ができるサイトです。人気講座のある入門スクールや独学できる学習サイトを、口コミ・評判で比較してランキング形式でご紹介しています。