Python PEP8 ~その参 コメント~

これまで

Python PEP8 ~その壱 import~
Python PEP8 ~その弐 無駄な空白は削除~

意識すべき点

その１

コードと矛盾するコメントは、コメントしないことよりタチが悪いです。

その２

コメントを書くときは、あなたが今書いている言葉の他の話者から見ても、明快かつわかりやすいコメントにしましょう。

その３

コードを変更した時は、コメントを最新にすることをいつも優先させてください！

コード変更後、コメント変更するのいつも忘れがち...気を付けよ。

ブロックコメント

ブロックコメントは、一般的にその後に続くいくつか（またはすべて）のコードに適用され、そのコードと同じレベルにインデントされます。

ブロックコメントの各行は (コメント内でインデントされたテキストでない限り) # とスペースひとつではじまります。

スペース忘れずに。

num_list = [1, 2, 3, 4, 5]


for num in num_list:
    # 2で割り切れるならeven_listに追加
    if num % 2 == 0:
        even_list.append(num)
    else:
        odd_list.append(num)

インラインコメント

インラインコメントは控えめに使いましょう。

インラインコメントは、文と同じ行に書くコメントです。文とインラインコメントの間は、少なくとも二つのスペースを置くべきです。インラインコメントは # とスペースひとつから始めるべきです。

スペース忘れずに。

a = 5  # 5をaに代入

ドキュメンテーション文字列(別名 "docstrings")

docstringとは

モジュール、関数、クラス、またはメソッド定義の最初のステートメントとして出現する文字列リテラル

通常、すべてのモジュールには docstring が必要

import pandas as pd

"""csvからデータを読み取る"""
def read_data():
    data = pd.read_csv('data.csv')

docstringに関しては下記のリンクで別途詳しく記述してあります。

英語を話さない国出身の Python プログラマの方々へ

あなたのコードが、自分の言葉を話さない人に 120% 読まれないと確信していなければ、コメントを英語で書くようにお願いします。

最後に

コードを書くことで一所懸命だった。
これからはコード規約を頭に入れ、コードを書いていく！