読めるように書く
Google社内では、主要なプログラミング言語について Readability というのが存在します。 「C++のReadabilityを持っている」とは、C++のコードをスタイルガイドに従ったコードを読み書きできる能力があることを意味しています。社内のコードベースと一貫したコードで開発できるということです。Readabilityをもっていない人は、Readabilityを持っている人にcode reviewしてLGTM/Approvalを貰わないとコードをrepositoryにcommit/submitすることができません。
コードベースを管理しやすくする方法のひとつは、強制的に一貫性を持たせることです。どんなプログラマでもコードを見ればすぐに理解できる、これはとても重要なことです。 全員が一貫性のあるスタイルを守って規則にしたがっていれば、それぞれのシンボルが何を意味しているのか、どの不変式が真なのかといったことが、簡単な「パターンマッチング」により推測できるようになります。よく使うイディオムやパターンを作っておくと、コードはとても理解しやすくなります。そうはいっても、スタイルを逸脱するのに十分な理由がある場合もあるでしょう。しかし、それでもなお、私たちは一貫性を保つことが重要だと考え、スタイルをそのまま適用することを選んでいます。
自分の好きな言語の Style Guide を一度読んでみるのも良いかもしれません
とはいっても Coding Convention が厳しくない状況でコードを書く場合もありますよね
個人的にその場合は、できるだけファイルやレポジトリの中でスタイルが一貫性が保たれるように書いています
――では、外部とのインターフェースには具体的に何を書くべきでしょうか？
園田：一般論として最初に検討するべき候補はあります。「（1）事前条件」「（2）事後条件」「（3）不変条件」「（4）入力の意味」「（5）出力の意味」「（6）副作用」「（7）計算量」です。要するに、利用する側が知っておくべきだけれど、コードの中身を見なければ容易には分からないものです。
園田：検討したけれどやらなかったことも、手法の概要と、うまくいかない理由をセットにしてコメントに書くべきです。あるいは、小さな問題を修正しようとするとコードが複雑になったり性能が落ちたりするので、あえて放置することもあります。
名付けにおいて最も気にするのは“一貫性”です。「標準ライブラリの○○という機能はこういう命名体系なのに、こちらは違う」となると、読者はわざわざそれを覚えなければいけなくなってしまいますから。
同じような振る舞いをするものには同じような名前を付けることで、読者が知っておくべき事前情報の量を減らすことができます。
個人的にコメントをあまり残さずに書いてしまいがちなのですが、シニアな人ほどちゃんとコメントやログメッセージを丁寧に書いているイメージがあるので、大事にしていきたいと思っています
他の部分も、引用するときりがないくらい、とても勉強になりました
具体的な書き方 - 参考文献
名前そのままに色々載っています
引数に関数を渡すと、真ん中だけ違う関数を抽象化できるよ、って話が１番印象に残ってます
Python の contextlib.contextmanager や Ruby の File.open("foo.txt") { ... } も同じように真ん中だけ別処理するための抽象化ですね
具体的な書き方については 第2部 ~ 第4部 あたり