注目キーワード
  1. Photoshop
  2. Python
  3. Raspberry Pi
  4. Arduino

Python 関数・クラス下の綺麗なコメントアウトの書き方

ここでは「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」からセンサ値を取得するプログラムで、当ブログでも紹介しています。

ラズパイでBMX055の使い方と地磁気などのセンサ値を取得してみた

 

それでは上記のコードを例に詳しく説明していきます。

 

関数の説明

まず、関数def直下のコメントアウトに注目してみます。

class BmxData(object):
    """ Get Bmx055 sensor data 
    """

これは

関数・クラスが何をするのか

を示したコメントアウトになります。

実際に上記では

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
    """

となっていますね。

 

このなかで、大切なのは

Returns:

で戻り値の説明をしていることです。

 

プログラムを書いた本人は、どんな引数・戻り値にしたか直ぐに分かると思いますが、他の人が見ると直ぐに理解できないことが多いです。

したがって上記のように説明を書いておくことが良いとされています。

 

関数に引数を取る場合は

Args:

Arguments:

のどちらかで引数の説明を記述しておきましょう。

 

記述方法はGithubから引用したコメントアウトを参考にしてもらうと、分かりやすいと思います。

 

以上、関数・クラス下の綺麗なコメントアウトの方法でした。

コメントアウトをコーディング規約に沿って書くだけで、万人に見やすいプログラムになります。

一つ一つの関数にコメントを書くのは大変かもしれませんが、慣れてくれば、関数にコメントが無いのに違和感を覚えるようになると思います。

是非マスターして、綺麗なコードスタイルを目指してください!

 

また、Pythonをもっと深く学びたい!極めたいという方は

シリコンバレー流 Pythonの基礎・応用を学べる「Udemy」のこちらのコースがオススメです。

僕も受講しましたが、Pythonのコードスタイルが以前とは格段に見やすくなりました!

データ解析、データベース、自動化なども満遍なく学べるので、Pythonを極めたい方は是非上記のリンクからのぞいてみてください。

 

お疲れ様でした。

python-funccodestyle-top
学びに関する情報をチェック!