Edited at

「コメントは書くな」

同僚だったロシア人のMはとにかくすごいエンジニアで、給料について社長ともめていたかと思えば、スーパーデプロイシステムを一人で作り上げていたり、Python推しの会社の中で、各所を説き伏せてTypeScript on node.jsの導入を進めたりしていた。

皮肉屋で、だれかれかまわず議論をふっかけていたが、とにかく仕事が速くて品質がよいので絶大に信頼されていた。

私は開発者としてMから様々な教えを授けられた。当時私はPHPerあがりのひよっこで、日々ダメコードを生産していた。

ある日Mにコードレビューを依頼すると、こんなことを言われた。

「堀さん!ソースコードにコメントを書いてはいけない!」

// connect to the database named "mysql" on the localhost

val driver = "com.mysql.jdbc.Driver"
val url = "jdbc:mysql://localhost/mysql"
val username = "root"
val password = "root"

// initialize
var connection: Connection = null

try {
// make the connection
Class.forName(driver)
connection = DriverManager.getConnection(url, username, password)

// create the statement
val statement = connection.createStatement()

// get data from user table
val resultSet = statement.executeQuery("SELECT host, user FROM user")
while (resultSet.next()) {
val host = resultSet.getString("host")
val user = resultSet.getString("user")
// print host and user
println("host, user = " + host + ", " + user)
}
} catch {
case e => e.printStackTrace
}
connection.close()

(ソースコードはイメージです)

教科書なんかを読むと、ソースコードには適宜コメントを書いて読者に動作を伝えましょう、と書いてあるものである。

よくよく話を聞いてみると、こういうことだった。


  • きちんと書かれたコードは、それ自体が動作を明確に表す

  • その場合、コメントは読者にとってノイズにしかならないし、ソースコードを太らせる

  • だから、ソースコードがドキュメントの役割を果たすような、きれいなコードを書かなければならない

  • 止むに止まれぬ理由で汚いコードを書いてしまった時に、意図を伝える最後の手段がコメントである

ひよっこの私は納得するしかなかった。

同様の教えに「ドキュメントを書くな」というものがあるのだが、それはまた別のお話。


この記事を少しでも建設的な結果に導きたいので、いくつか追記します。


  • まず、あらゆるコード内コメントが悪だと言っているのではない。それはMも思ってないし、私も思っていない。

  • この記事はちゃんとした技術的記事というより、軽いプログラミングエッセイを書くつもりで書かれた。


    • そのため、このような扇情的なタイトルになった。この点はちょっと申し訳ない

    • でも(当時の私が)ビックリしたんだもん😅



  • サンプルコードは当時私が書いていたようなコードを模したもので、今はこんなコードは書かない😅

いくつかの反響に対する私の考え:


  • 「日本語ネイティブがそこまで達するのは無理」


    • 英語がんばろう。少なくとも英語で命名しているなら、コード内の英語表現は最大限気を遣おう

    • 別アプローチとしては、弊社内のあるプロジェクトでは日本語プログラミングに挑戦している



  • 「プロジェクトの規約で無理」


    • 環境を変えよう。それは率先してプロジェクトの意識を変えていくことかもしれないし、プロジェクトを去ることかもしれないが



興味を持った方に:



  • Stop Writing Code Commentsという記事を同僚に教わった。より具体的に、よくないコメント例が列挙されている

  • 書籍「リーダブルコード」


    • 特に命名のところは大好き

    • Mも「命名は小さなコメントのようなもの」と言っていた