ここでは「Python」の綺麗なコメントアウトの書き方について紹介します。
この記事を読むことで
Pythonプログラム内のコメントアウトの書き方
関数・クラス下のコメントアウト方法
を実際のプログラムを用いて解説していきます。
どこへでも通用するコメントアウトの書き方を覚え、綺麗なPythonicコードを目指しましょう！
それでは早速始めていきますね。
綺麗なコードスタイルとは
まず綺麗なコメントアウトを書く上で知っておきたいのは「コードスタイル」についてです。
ざっとこの説明と、一例を紹介します。
Pythonのコードスタイル
Pythonには読みやすいコードスタイルとなるように、標準ライブラリ「PEP8」などのコーディング規約があります。
そのため、コーディング規約に沿ったプログラムの書き方が綺麗なコードスタイルと言えるでしょう。
Pythonのコードスタイルをチェックするのに
PEP8
Flake8
Pylint
などが挙げられます。
PEP8は、コーディング規約が優しく、Flake8は中間、Pylintは厳しいという違いがあります。
PEP8には「autoPEP8」というライブラリもあり、自動でコードスタイルを直してくれるので、コードスタイルを覚えるまでは、autoPEP8を使うのも十分ありだと思います。
これらのコーディング規約を守ってプログラムを書くのを目指しましょう。
綺麗なコードスタイルの一例
Pythonにコードスタイルがあることをさらっと上で説明しましたが、実際にどのように書くのが綺麗なコードスタイルなのかを、実際のプログラムを例に紹介してみます。
紹介するにあたり、Github：xiaochus/YOLOv3 を参考にしたいと思います。
この方の「darknet53.py」を開いてもらい、def関数下のコメントアウトを見てもらうと
xiaochus/YOLOv3/model/darknet53.py
"""Convolution Unit
This function defines a 2D convolution operation with BN and LeakyReLU.
# Arguments
x: Tensor, input tensor of conv layer.
filters: Integer, the dimensionality of the output space.
kernels: An integer or tuple/list of 2 integers, specifying the
width and height of the 2D convolution window.
strides: An integer or tuple/list of 2 integers,
specifying the strides of the convolution along the width and
height. Can be a single integer to specify the same value for
all spatial dimensions.
# Returns
Output tensor.
"""
※ 引用 Github：xiaochux/YOLOv3/model/darknet53.pyより
のようにコメント内に
関数の説明引数の説明
戻り値の説明
が記載されているのが分かります。
このように各関数ごとにコメントアウトを記載することで、対象の関数が何をするのかが分かるので、見やすく綺麗なコードスタイルと言えるでしょう。
したがって、関数・クラス下に上記のようにコメントアウトする手段を紹介していきます。
関数・クラス下のコメントアウト
先ほど紹介したコメントアウトを参考に、センサデータ取得プログラムにコメントアウトしてみたので紹介します。
bmx_data.py
"""BMX055 sensor data for robot
"""
import math
import numpy as np
import time
from smbus import SMBus
class BmxData(object):
""" Get Bmx055 sensor data
"""
def __init__(self):
# Initialze I2C adress of acc, gyro, mag
self.ACCL_ADDR = 0x19
self.ACCL_R_ADDR = 0x02
self.GYRO_ADDR = 0x69
self.GYRO_R_ADDR = 0x02
self.MAG_ADDR = 0x13
self.MAG_R_ADDR = 0x42
self.flg = 0
self.i2c = SMBus(1)
def acc_value(self):
"""acc_value function is get acc data
Returns:
list: The return value.
acc_data[0] is acc x axis value
acc_data[1] is acc y axis value
acc_data[2] is acc z axis value
"""
data = [0, 0, 0, 0, 0, 0]
acc_data = [0.0, 0.0, 0.0]
try:
for i in range(6):
data[i] = self.i2c.read_byte_data(self.ACCL_ADDR,
self.ACCL_R_ADDR + i)
for i in range(3):
acc_data[i] = ((data[2 * i + 1] * 256) +
int(data[2 * i] & 0xF0)) / 16
if acc_data[i] > 2047:
acc_data[i] -= 4096
acc_data[i] *= 0.0098
except IOError as e:
print("I/O error({0}): {1}".format(e.errno, e.strerror))
return acc_data
このコードは9軸センサ「BMX055」からセンサ値を取得するプログラムで、当ブログでも紹介しています。
それでは上記のコードを例に詳しく説明していきます。
関数の説明
まず、関数def直下のコメントアウトに注目してみます。
class BmxData(object):
""" Get Bmx055 sensor data
"""
これは
を示したコメントアウトになります。
実際に上記では
とあるので、BMX055のセンサ値を取得するクラスだと分かります。
Pythonのコードスタイルは
クラス： キャメルケース
関数 ： スネークケース
で書くのが好ましいとされているのですが、時々その関数が何を示すのか分からないときがありますよね。
そんなときに、コメントアウトでどんな関数かを書いておけば、誰が見ても理解することができますよね。
Pythonでは、こういった一つ一つの配慮が大切になってきます。
引数・戻り値の説明
続いて、引数・戻り値の説明について「def acc_value(self):」に注目してみると
def acc_value(self):
"""acc_value function is get acc data
Returns:
list: The return value.
acc_data[0] is acc x axis value
acc_data[1] is acc y axis value
acc_data[2] is acc z axis value
"""
となっていますね。
このなかで、大切なのは
で戻り値の説明をしていることです。
プログラムを書いた本人は、どんな引数・戻り値にしたか直ぐに分かると思いますが、他の人が見ると直ぐに理解できないことが多いです。
したがって上記のように説明を書いておくことが良いとされています。
関数に引数を取る場合は
Args：
Arguments：
のどちらかで引数の説明を記述しておきましょう。
記述方法はGithubから引用したコメントアウトを参考にしてもらうと、分かりやすいと思います。
以上、関数・クラス下の綺麗なコメントアウトの方法でした。
コメントアウトをコーディング規約に沿って書くだけで、万人に見やすいプログラムになります。
一つ一つの関数にコメントを書くのは大変かもしれませんが、慣れてくれば、関数にコメントが無いのに違和感を覚えるようになると思います。
是非マスターして、綺麗なコードスタイルを目指してください！
また、Pythonをもっと深く学びたい！極めたいという方は
シリコンバレー流 Pythonの基礎・応用を学べる「Udemy」のこちらのコースがオススメです。
僕も受講しましたが、Pythonのコードスタイルが以前とは格段に見やすくなりました！
データ解析、データベース、自動化なども満遍なく学べるので、Pythonを極めたい方は是非上記のリンクからのぞいてみてください。
お疲れ様でした。