Posted at

ソースコードのコメントに書いてあると嬉しいもの

Twitterでソースコードにコメントを書くべきかどうかという話で盛り上がってるみたいので、コメントに書いてあると個人的に嬉しいものを3つ挙げようと思います。


アルゴリズム名、出典論文

コメントが不要なソースコードが理想と語られることが多いです。これは説明をわざわざしなくて済むような読みやすさでソースコードを書こうという考えから来るものです。

しかし、説明がないと理解するのが難しい場面があります。その1つが、名前がつくレベルの精錬されたアルゴリズムです。例えば、ユークリッド互除法。これは最大公約数を効率的に計算するアルゴリズムですが、数学に疎くてユークリッド互除法を知らない人からすると、なんでこれで最大公約数が計算できるのかという疑問が湧きます。なので、コメントにアルゴリズム名が書いてあると、そういう人にはソースコードを理解する手助けになります。

論文を読んで実装した場合は出典をコメントに書いて欲しいですね。その道の専門家じゃないとわからない部分とはっきりわかりますし、後で実装を見直す場合に役に立ちます。出典がわからないと、後でコードを読んだとき、なんでこんな実装になったのかという疑問が湧くことになります。


苦し紛れに実装した部分

「本当は〇〇したいんだけど、〇〇という理由により〇〇せざるを得なかった」という感じのコメントですね。苦し紛れに実装しないといけなかった原因には無茶な要件・レガシーなコードのまずさ等の地雷があるので、コメントにそれを書くことによって、安易に地雷を踏み抜くことを避けることができます。


歴史的経緯の説明

歴史的経緯により謎実装になってる場合は結構あると思うので、歴史的経緯の内容を簡単に書いてあると嬉しいですね。「歴史的経緯により」という一言で済ませられるのは最悪です。