見やすいソースの書き方について

[Libra]

見やすいソースにするにはどうすればよいか、について質問します。


・１行コメントが理想
・if( x == 1 ){・・・のように半角スペースを入れる
・ブロックコメントをしっかり入れる
・字下げを行う
・関数内ローカル変数に関しても何に使うのかのコメントを入れる

等を行っているのですが、上で挙げた点、添付ファイルの中で書き方に関して改善点などあれば教えていただけないでしょうか？お願いします。

[kazuoni]

本当に個人的で、職場等を経験した事がないので分かりませんが・・・

if(...){
    ...;
}
より
if(....)
{
    ...;
}

のが好きですｗｗ
現場ではどのようにしているのですかね＾＾；

[たかぎ]

最も重要なのは、コメントがなくても理解できるソースコードを書くことです。

[nayo]

>最も重要なのは、コメントがなくても理解できるソースコードを書くことです。

ハッとさせられました
私がコメント文を多用するのは可読性の低いソースコードになってるからなのか
これは今後意識していきたいです

基本的（？）なことですが個人的に変数名や関数、クラス名などを分かりやすいものにしたり、
インデントをしっかり行う、一つの関数内で行う処理は一つだけ、
などとすると見やすい気がします

当たり前かもしれませんがコメントの書き方も

// aにb+1の値を入れる
a = b + 1;

などと処理をそのまま書くのでは意味がないのでなぜその処理を行うのか目的を書くようにする、
などでしょうか

参考になるかは分かりませんが一応こちらもどうぞ
http://q.hatena.ne.jp/1142519342

[たかぎ]

コメントで書くべきなのは、「何をやっているか」ではなく、「なぜそう書いたのか」です。
これは、コメントでなくても、外付けのドキュメントでもかまいません。

例えば、実装方法を検討した結果、あるいは実際に試してみた結果、うまくいかなかったからこうしたとか、トレードオフに対してどう考えて判断を下したか、などです。

> 基本的（？）なことですが個人的に変数名や関数、クラス名などを分かりやすいものにしたり、

識別子の命名は大切ですね。
英語で識別子を命名するときにやってしまいがちなのは、同じ意味の用語に対して複数の訳語をつけてしまうということです。これをやってしまうと、とたんに分からなくなります。

移植性の制約がないのであれば、日本語で識別子を命名することを検討してみるのもよいでしょう。
日本語識別子というと頭ごなしに否定する人が多いですが、（移植性以外で）駄目な理由をきちんと説明できる人を見たことがありません。

> インデントをしっかり行う

これは当たり前のことですが、逆にインデントを崩すテクニックも覚えておくと便利です。
特徴的な処理など、特に目立たせたい箇所を、わざと１桁目から書く、などです。

あと、括弧の位置やスペースの有無、インデント幅などは、一貫性さえあればどうでもよいことです。
こうした"箸の上げ下げ"に相当することまで規定したコーディング規約を良く見かけますが、そんなことを規定するぐらいなら、そうした"くだらない議論をしない"ことを規定するほうがずっとましです。
indentやastyleのようなツールを使えば後からいくらでも整形できるわけですから。

[Libra]

＜最も重要なのは、コメントがなくても理解できるソースコードを書くことです。

コメントを入れる＝可読性が上がると同義と考えてしまっていました。
以前の自分のソースは、自分は読めるが他の人が見たら何をやってるのか分からないようなソースの書き方だったので、それを改善するため、ソースの簡略化とコメントを入れる作業を同時進行でやって行きましたが、自分はまだソースを読み解く力が弱いのでコメントに頼ってしまう節があったようです・・・。


＜参考になるかは分かりませんが一応こちらもどうぞ
http://q.hatena.ne.jp/1142519342

コーディング規約等はそれぞれが矛盾しあっている場合があるので、それをどう取捨選択していくかが重要だと思いました。リンク先でも、可読性が最重視されていました。


＜コメントで書くべきなのは、「何をやっているか」ではなく、「なぜそう書いたのか」です。

これも盲点でした。「何をやっているか」が分かれば良いと言うところで思考が止まっており、
その"次"の段階が抜け落ちていました。
可読性の高いソースを書くことで何をやっているかがすぐにわかり、コメントで「何故そう書いたのか？」が判るのが理想ですね。


<移植性の制約がないのであれば、日本語で識別子を命名することを検討してみるのもよいでしょう。
日本語識別子というと頭ごなしに否定する人が多いですが、（移植性以外で）駄目な理由をきちんと説明できる人を見たことがありません。

識別子を日本語で書くのは行けないという暗黙の了解があるのかと思っていました・・・。日本語だと変数名が長くなりがちなので避けるというだけなのでしょうか？


＜逆にインデントを崩すテクニックも覚えておくと便利です。特徴的な処理など、特に目立たせたい箇所を、わざと１桁目から書く、などです。

このようなテクニックは知りませんでした。目立たせたいところはコメントをがっつり入れていただけだったので、このテクニックも習得したいと思います。


＜括弧の位置やスペースの有無、インデント幅などは、一貫性さえあればどうでもよいことです。
こうした"箸の上げ下げ"に相当することまで規定したコーディング規約を良く見かけますが、そんなことを規定するぐらいなら、そうした"くだらない議論をしない"ことを規定するほうがずっとましです。

これも、そういったコーディング規約があるのだからこれも重要事項の一つだと思っていました＾＾；


Ｃ言語の基本の文法の書き方が載っている参考書にはこのようなことはほとんど載っていないので、ものすごく勉強になりますｍ(_ _)ｍ 。

[たかぎ]

> 日本語だと変数名が長くなりがちなので避けるというだけなのでしょうか？

そんなことはないでしょう。
例えば、「measurement」または「measuring」と書くのと、「計測」と書くのでは、明らかの後者の方が短いですね。
ここでも、仕様書で「計測」と書いているのをソースコードに反映する際に、人によって「measurement」とか「measuring」とか、さらには「counting」のような訳語をバラバラに付けてしまうと、収拾が付かなくなります。

[Sleepy]

添付頂いたソースはコメントが冗長の様な気がします。

仕事で見た全く無意味なコメントにこんなのがありました。
int i = 0; /* 変数iに0を代入する */

例えばこんなコメントにすべきです。
int i = 0; /* 初期化しなくても実害はないが警告防止のため初期化 */

個人的に気をつけている事をいくつか挙げます。
・グローバル変数はなるべく使用しない。
　使用する場合は宣言1箇所、設定1箇所、後は参照のみにする。
・インデントは3段程度まで、3段を超えるなら分割を検討。
・1関数100行程度まで、100行を超えるなら分割を検討。
・1行100文字程度まで、100文字を超えるなら折り返す。
・thenの処理の行数＞elseの処理の行数なら条件を反転しthenとelseを入れ替える。
・途中脱出を使用し、全ての条件を満たしたときのみ最後の処理に到達。
・一定のパターンによる条件羅列なら、テーブルロジックに置き換える。
等々。

未来の自分は自分ではなく他人です。
他人に読めないソースは、そのうち自分でも読めなくなります。

[TOMONORI]

大事なことを少しまとめると

    自己解説的なコードを書く
        たいちろうさんの仰っていた事。プログラマの腕の見せ所。

    変数名は意味を明瞭に
        誰が読み手となりうるのかも考慮した上で。

    コメントはプログラマへのメッセージ
        Sleepyさんが不幸にも遭遇したような例はプログラマへの冒涜ですね。逆に、
        //! この部分は複雑なのでコーヒーを一杯飲んでから落ち着いて読め
        みたいなコメントなら大丈夫(冗談ですよ？)

    インデントの好みは人それぞれ
        インデントについての議論は"するだけ無駄"というのが先人達の
        大いなる努力によって導き出された結論です。統一されてないのはだめですが。

とりあえずはこんなところでしょうか。
細かいところを挙げるときりがないので、とてもよい参考書を紹介しておきますね。

    『コード・クラフト エクセレントなコードを書くための実践的技法』
     （毎日コミュニケーションズ）

自分が出版社差別をやめるきっかけになった本。Codeシリーズの中でも最も読みやすく、
これからプログラマになる人は(一応実務経験者用っぽく書かれていますが)読むといいです。

変数のネーミングルールですが、自分はすべて英語で書いています。英語でのネーミングルールは
一般的なコンベンションがよく成熟しているので、適切な接頭辞やイディオムを使用すれば
読み手に誤解を与えることなくスマートで適切な命名が可能です。
ただし、これは個人的な開発の場合に限ります。チームプログラミングなど複数人で
開発する場合やシステムの保守(経験なし。すみません)なんかは他の人と合わせるべきでしょう。

最後に、サンプルソースは内部の実装っぽいのであんまり見た目にこだわる必要は・・・
などと思ってしまったのですが、そんな返事は期待してないかなと思って最後に回しました。
自分なら変数名は２、３文字程度で済ませてしまいそうです。みたところ何らかの
ユーティリティライブラリのようですが、見た目をこだわるのはこのコードの
クライアント側ではないでしょうか。そして、クライアントがより抽象的で美しいコードを
書けるように具象部分で頑張るのが正しいと思います。

長くなってしまったので、この辺で失礼します。

[組木紙織]

読みやすいコードに繋がるかどうかは分かりませんが、最近はコメントを書く場所と書かない場所
を考えるように気をつけています。

Libraさんのやられているようにそれぞれの関数の頭部分に引数の意味、戻り値の意味、機能
だけでなく、事前条件、事後条件、不変条件を書き、実行時に常にテストするように組んでいます。
(もちろんテストはDebugモードのみになるようしています。)
これをすることによってコーディング速度は遅くなりましたが、バグが出にくく、出ても修正が楽になりました。

それ以外では出来るだけコメントを書かずに、関数名、変数名で意味を取れるように気をつけています。
(変数名だけでなく、関数名にも命名規約を大雑把にですが、持っています。)


アプリケーションハンガリアンについて調べてみるのも参考になると思います。
(ただのハンガリアンだと私の意図と異なります)

[たかぎ]

> アプリケーションハンガリアンについて調べてみるのも参考になると思います。
> (ただのハンガリアンだと私の意図と異なります)

今のところまったく実践できていませんが、テンプレート仮引数にハンガリアンを適用すると有効な気がします。
それがシステムハンガリアンであったとしても（型名に付けるわけだらかちょっと違うか...）。

例えば、

入力反復子　ii
前方反復子　fi
ランダムアクセス反復子　ri
文字様型　ch
列　seq
アロケータ　a
入力ストリーム　is
出力ストリーム　os
入出力ストリーム　ios

などです。

現状では仮引数名全体でこれらを表現していますが、それだと、もっと突っ込んだ意味を表せません。
近いうちに一度試してみたいと思います。