SSブログ

コードレビューの視点 018 [コードレビューの視点]

情報を付加しないコメントに注意する

プログラミングにおいては日本語でプログラムを書くこと、つまりクラス名、メソッド名、変数名を日本語にしてプログラミングすることはまれだと思います。しかし、コメントを日本語で書くことは普通に行われています。そうすると、次のようなコードを目にすることになります。
// モデル情報を取得する
Model m = config.getModelInfo()
これはコードを読めば分かることを説明しているコメントに過ぎないのですが、日本語で書いてあるので何らかの情報を付加しているような印象を与えます。これを英語で書いたとしたら次のようになるでしょう。
// Gets the model info
Model m = config.getModelInfo()
明らかに「同じこと」を二回書いていることになります。したがって、そもそもこのようなコメントは書かないわけです。

コメントはコードから読み取れない、あるいは分かりにくいことを説明するために書くわけです。しかし、日本語で書くことにより次のようなコメントを目にすることがあります。
  • 上記のようにメソッド名が表す意味をそのまま日本語で書いている
  • メソッド名が不適切に命名されて処理内容が読み取れないので、日本語のコメントで説明している
  • メソッド名が不適な命名で処理内容が読み取れないけれど、そのメソッド名がそのまま日本語に訳されてコメントとして書かれている
コードを読みやすく理解しやすいように書き、その上で読み手に付加情報を与えるためにコメントを書くのです。付加情報のない無意味なコメントが書かれていないか、メソッド名などを適切に変更すればコメントが不要になるのではないかという視点でコードをレビューする必要があります。

『プログラミング言語Go』翻訳作業が終了しました(3) [golang]

プログラミング言語Go

プログラミング言語Go

  • 作者: Alan A.A. Donovan
  • 出版社/メーカー: 丸善出版
  • 発売日: 2016/06/20
  • メディア: 単行本(ソフトカバー)

諸事情により、発売日が6月20日に延期されたようです。

『プログラミング言語Go』翻訳作業が終了しました(2) [golang]

プログラミング言語Go

プログラミング言語Go

  • 作者: Alan A.A. Donovan
  • 出版社/メーカー: 丸善出版
  • 発売日: 2016/06/15
  • メディア: 単行本(ソフトカバー)

目次です。
日本語版によせて iii
まえがき xiii
第1章 チュートリアル 1
第2章 プログラム構造 29
第3章 基本データ型 57
第4章 コンポジット型 91
第5章 関数 135
第6章 メソッド 177
第7章 インタフェース 197
第8章 ゴルーチンとチャネル 251
第9章 共有された変数による並行性 297
第10章 パッケージとGo ツール 327
第11章 テスト 349
第12章 リフレクション 379
第13章 低レベルプログラミング 407
訳者あとがき 423
索引
翻訳本の中のコードのコメントは翻訳されていますが、サンプルコードのダウンロードは英語版のサイト(こちら)から行ってもらいます。したがって、ダウンロードされたサンプルコード内のコメントは翻訳されていません。

「まえがき」に書かれていますが、何らかのプログラミング経験がある人が対象となっています。
この本では、みなさんが一つ以上の言語でプログラミングした経験があることを想定しています。C、C++、Java などのコンパイル言語、あるいはPython、Ruby、JavaScript などのインタプリタ言語のどちらでも構いません。したがって、全くの初心者向けの本のようにすべてを事細かに説明す ることはしません。
「まえがき」より
もちろん、言語仕様に関する部分はきちんと細かく説明されています。目次を見てもらえば分かるように、リフレクションやcgoを使った低レベルのプログラミングについても解説されています。

以下のサイトでも予約注文可能です。

技術書のレビュー(6) [プログラマー現役続行]

Core Java, Volume II--Advanced Features (10th Edition) (Core Series)

Core Java, Volume II--Advanced Features (10th Edition) (Core Series)

  • 作者: Cay S. Horstmann
  • 出版社/メーカー: Prentice Hall
  • 発売日: 2016/10/09
  • メディア: ペーパーバック

Vol.1のレビューは時間切れで全部の章を行うことができませんでした。Vol.2のレビュー依頼がきましたので、全部の章をレビューできるかどうかは分かりませんがレビューすることになりました。

『プログラミング言語Go』翻訳作業が終了しました [golang]

プログラミング言語Go

プログラミング言語Go

  • 作者: Alan A.A. Donovan
  • 出版社/メーカー: 丸善出版
  • 発売日: 2016/06/15
  • メディア: 単行本(ソフトカバー)

2015年4月20日から原著の原稿のレビューを始めて、レビューが終わったのが2015年9月5日でした。その間に、二回読み返しています。翻訳は2015年9月13日に着手し始めて、私のすべての作業が昨日(2016年5月8日)終了しました。今日、入稿となり印刷所での印刷の準備が始まりますので、予定通り6月15日刊行となります。

今回は、原著のレビューに98時間、翻訳に473時間を費やしたことになります。ちなみに『APIデザインの極意』は、翻訳だけでしたが500時間を費やしています。これは、私が私的時間に費やした時間であり、出版社の担当者やレビューアによるレビューを加えると多くの時間が費やされたことになります。また、社内のGo言語研修では翻訳原稿の第7章までを渡して研修を今まで行っていますので、受講生からの誤りの指摘も行われています。

翻訳作業は、すべてMacBook Air 11インチかMacBook 12インチのどちらかでLaTeX(TeXLive)を使って行いました。翻訳作業そのものは自宅だけでなく、通勤電車(「通勤電車の書斎化」)、スターバックスやマクドナルドなどとさまざまな場所で行いますので、常に持ち歩いているのは軽い方のMacBook 12です。2台持っている理由は、一台が壊れて修理に出している間に作業ができなくなるような事態を想定してです。幸い、今回の翻訳中にどちらかが壊れることはありませんでした。LaTeXファイルはすべてgithub.comのプライベートリポジトリで管理しています。出版社への納品はLaTeXファイル一式です。今回は、翻訳途中で不測の事態に備えて、ファイルの一式をほぼ毎日、出版社に送っていました。
※ 英語版はtroffで組版されたようです。詳しくは、こちら

本文だけでは分かりにくいと思われる箇所に関しては、訳注を追加しています。今回は、33か所に訳注を追加しています。また、原著の正誤表の5月8日時点までの修正はすべて反映されています。原著の原稿のレビューを含めて、著者のアラン・ドノバンやブライアン・カーニハンとやり取りした電子メールは350通を超えました。

以下のサイトでも予約注文可能です。