前回の記事と並行して、こんなコメントの書き方してますっていうのを軽く書いておこうかなと。

どこかで見たわけでもなく、自分なりに「これが一番見やすくて、邪魔にならなくていいかな」って思ったのでこの書き方をしてます。

今回は以下の3つの例から紹介します。

邪魔なソースコードコメントの例
ソースコードコメント無しの例(ついでに改行も無し)
僕なりのソースコードコメントの例

使用するのは、この前Qiitaに上げたバレンタインのやつ。

邪魔なソースコードコメントの例

# 必要なライブラリをimport
import sys  # 引数取得に必要
import math  # 切捨てに必要

# 引数がなかったら終了
if len(sys.argv) <= 1:
    print("引数入れてね")
    exit()
# 5以上の奇数でない場合は終了
num = int(sys.argv[1])
if num < 5 or num % 2 == 0:
    print("引数は5以上の奇数で入れてね")
    exit()

# 中心から上を作る
top = ""
top_num = math.floor(num / 2) - 1
for i in range(0, top_num):
    top = " "  # 整形のため半角スペースを入れておく
    # 左側にスペースを埋める
    for j in range(0, top_num - i - 1):
        top += "  "
    # 先頭行の場合は"／￣＼／￣＼"を入れる
    if i == 0:
        top += "／￣＼／￣＼"
    # 先頭行でない場合は、"／"と"＼"の間にスペースを埋める
    else:
        top += "／"
        for j in range(0, 2 * i + 4):
            top += "  "
        top += "＼"
    print(top)  # 出力

mid_space = ""
mid_num = math.floor(num / 2) - 1
for i in range(0, mid_num):
    mid_space += "  "
print("｜" + mid_space + " LOVE " + mid_space + "｜")

btm = ""
btm_num = math.floor(num / 2)
for i in range(btm_num, -1, -1):
    btm = " "  # 整形のため半角スペースを入れておく
    for j in range(0, btm_num - i):
        btm += "  "
    btm += "＼"
    for j in range(0, i * 2):
        btm += "  "
    btm += "／"
    print(btm)

topだけで疲れたので書くのやめた。
コメントを書くだけで時間かかるし、コメントだけでぐちゃぐちゃしてる。
あと、詳細に書き過ぎてソースコードを日本語化してるだけになってる。
ソースコード内にコメントがあると可読性が落ちる。(日本語と英語が混在するため)
(少々過剰な書き方をしてるけど、汚いって事が伝わればいい)

ソースコードコメント無しの例(ついでに改行も無し)

import sys
import math
if len(sys.argv) <= 1:
    print("引数入れてね")
    exit()
num = int(sys.argv[1])
if num < 5 or num % 2 == 0:
    print("引数は5以上の奇数で入れてね")
    exit()
top = ""
top_num = math.floor(num / 2) - 1
for i in range(0, top_num):
    top = " "
    for j in range(0, top_num - i - 1):
        top += "  "
    if i == 0:
        top += "／￣＼／￣＼"
    else:
        top += "／"
        for j in range(0, 2 * i + 4):
            top += "  "
        top += "＼"
    print(top)
mid_space = ""
mid_num = math.floor(num / 2) - 1
for i in range(0, mid_num):
    mid_space += "  "
print("｜" + mid_space + " LOVE " + mid_space + "｜")
btm = ""
btm_num = math.floor(num / 2)
for i in range(btm_num, -1, -1):
    btm = " "
    for j in range(0, btm_num - i):
        btm += "  "
    btm += "＼"
    for j in range(0, i * 2):
        btm += "  "
    btm += "／"
    print(btm)

そもそも何のプログラムなのか全く分からない。
何がしたいのか、何ができるのか、何が出てくるのか、動かしてみないと分からない。
動かさずに解析したら多分１時間以上かかる。
解析をするにしても相当な集中力が必要。

僕なりのソースコードコメントの例

"""
Happy Valentine ;)
報われないおまいらのためにハートを授けよう。

#コマンド引数
argv[1] 5以上の奇数

#概要
ハートの上部→中部→下部の順番で出力
それぞれの部の行数については、以下となる
  - 上部：argv[1]/2-1
  - 中部：1
  - 下部：argv[1]/2+1
"""

import sys
import math

# 引数チェック
# - ５以上、奇数
if len(sys.argv) <= 1:
    print("引数入れてね")
    exit()
num = int(sys.argv[1])
if num < 5 or num % 2 == 0:
    print("引数は5以上の奇数で入れてね")
    exit()

# 上部
top = ""
top_num = math.floor(num / 2) - 1
for i in range(0, top_num):
    top = " "
    for j in range(0, top_num - i - 1):
        top += "  "
    if i == 0:
        top += "／￣＼／￣＼"
    else:
        top += "／"
        for j in range(0, 2 * i + 4):
            top += "  "
        top += "＼"
    print(top)

# 中部
mid_space = ""
mid_num = math.floor(num / 2) - 1
for i in range(0, mid_num):
    mid_space += "  "
print("｜" + mid_space + " LOVE " + mid_space + "｜")

# 下部
btm = ""
btm_num = math.floor(num / 2)
for i in range(btm_num, -1, -1):
    btm = " "
    for j in range(0, btm_num - i):
        btm += "  "
    btm += "＼"
    for j in range(0, i * 2):
        btm += "  "
    btm += "／"
    print(btm)

まず先頭にどデカくコメントを入れておく。
これで、このプログラムが何をしたくて何ができるのか、ソースを読まなくても分かるようにしておく。
あくまでも概要だけで、詳細な事はできるだけ書かない。

ソースコード内は、意味ある単位で改行を入れて、ブロック単位で簡単なコメントを入れておく。(#上部, #中部みたいな)
これで、このブロックで何ができて何をしたいのかが明確になる。

まあ、簡単に言えば「ドキュメンテーションコメントだけ書いてれば十分でしょ」って事です。

この書き方のいいところ

問題解決

そもそもプログラムというのは「xxxを解決したい」から書くものです。
その、解決したいxxxの概要を残しておけます。
つまり、今後同じ問題が発生した時に、日本語で検索して再利用する事も可能になります。

日本語と英語の分離

また、「日本語と英語を分離できる」というところも魅力です。
日本語と英語が混在しているから、ノイズが多く感じられて見づらくなるのであって、分離してしてしまえば個々で見る事が出来るという発想です。

まとめ

コメントを書かなさ過ぎると、

解析に時間がかかる
集中力も持たない。
そもそも何のプログラムか分からない

コメントを書き過ぎると、

日本語と英語が混在する事で可読性が落ちる
コメントとソースが同じになってしまい無意味なコメントになる
そもそもコメントを書くのに時間がかかる

なので、ドキュメンテーションコメントを書いて、概要を押さえつつ、日本語と英語を分離して、綺麗なソースコードを作っていきましょう。

関係ないけど、hatenaでPythonコード書いたら、うざいくらいシンタックスハイライト付けてくるな。
これじゃコメントとか関係なく余計に見辛くなるわ。

頑張らないように頑張る。

努力と怠惰の狭間

ソースコードコメントの書き方(我流)