これまでの内容としてはプログラムの処理にまつわる書き方について確認してきました。今回は定義した関数について説明を加えるための書き方について解説いたします。
ドキュメンテーション文字列(docstring)とは
ドキュメンテーション文字列とは関数の処理や、その仕様について説明した文章を関数に埋め込むための文字列です。コードに対しての説明文がコメントなら、関数に対しての説明文がドキュメンテーション文字列といった具合です。
何故関数にこのようなものを入れるかというと、自分が見直す際、もしくは第三者が関数を使う際に、どのように使ったらよいかわからず結局関数の中身を確認しないといけないということがあるかもしれません。ドキュメンテーション文字列を使えば関数に説明を入れられるので、あとで見返す手間が省け、コードの解読がスムーズに行えます。要はドキュメンテーション文字列は可読性の向上を目指そうというものになります。
実際にドキュメンテーション文字列を記載した関数にフォーカスを当てるとその内容が関数のプレビューとして表示されます。
docstringなしであれば関数のアドレスのようなものがプレビューされてますが、ある場合は、「Helloを出力する関数です。」と表示されていることがわかります。
ドキュメンテーション文字列(docstring)の書き方
それでは最後に書き方と例を見てみます。書き方は複数行にわたるコメントと同じで三連引用符 「“””」を使って記載します。普通に使えばコメントと見分けがつきませんので書く場所が重要なのですが、関数定義の一番上のゾーンに書けばドキュメンテーション文字列として認識されます。
実際にコードを見てみます。ドキュメンテーション文字列として認識されるものとそうでないものとで定義しておりますのでそれぞれどういう風に表示されるか見てみてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
#docstringとして認識されない def printHi(): print("Hi!") """Hi!を出力する関数です。""" #docstringとして認識される def printHello(): """Hello！！を出力する関数です。""" print("Hello ! !") printHi() printHello() |
関数はプログラミングの利便性を上げるためのものですが、肝心の関数に説明がなく結局理解するのに時間をかけているのであれば本末転倒です。そのため、ドキュメンテーション文字列に説明を書いて関数がどんなものかわかりやすいようにしてコードの可読性を上げるように心がけましょう。
今回はここまでです。
お疲れ様でした。
コメント