他人が読みやすいコーディングのコツ

質問

趣味でプログラミングをしているのですが、
現場で働いている人が見ても理解されるコードを
目指して学習をしています。

今、C/C++用のスタイルブックを買って読んでいます。
それと、デザインパターンの本を読んで、少しずつですが学習しています。

理解しやすいコードを書く練習として、他に「これはやっておけ」
というのがあれば教えてください。
よろしくお願いします。

回答No.11

shin_say · ベストアンサー

色々あがってますが、コレも必読かと。

　リファクタリング―プログラムの体質改善テクニック

コードを常にメンテナンス性の高い状態に保つテクニック、リファクタリングの本です。
デザインパターン、アナリシスパターン、XPに続くマイヒットです^^

参考URL：

http://www.amazon.co.jp/exec/obidos/ASIN/4894712288/qid=1113581192/sr=8-1/ref=sr_8_xs_ap_i1_xgl/249-6003960-9218738

回答No.10

matyrcry

処理の入口と出口をはっきりさせるくらいでしょうか。
関数の中でreturnを配置する場所と条件の規則性を考えてみるとか、
for/whileループを抜ける場所を１カ所にまとめるとか。
セマフォロックの解放など、抜ける前にやるべきことを忘れたりとか
が虫になることが多いんで、長い処理はデバッグ時に状況確認のタイ
ミングを確保できるように、分岐から戻ってきて確実に通る場所を
用意しておくと見やすいと思います。

回答No.9

kaha

>本を読み、自分でプログラムも組み、そのプログラム
>を人に見せて批評してもらい、人のプログラムも読ん
>でください。これだけすれば、絶対上達するはずで
>す。

上記は『Ｃプログラミング診断室』からの引用です。

サイトの紹介（参考ＵＲＬ）

参考URL：

http://rec.ncos.co.jp/link.html

回答No.8

ency

No6 ency です。

> > 練習として、他に「これはやっておけ」
>
> というものとして、コメントを一切書かず、コードだけで理解できるように
> 記述する訓練が有効です。

訓練という意味では、確かにそのとおりですね。＞No7 jacta さん。

あと「だらだらと長い関数を作らない」っていうのも付け加えておきます。
# 1000行以上ある関数を見たことがあるもので。。。

ちなみに、私の目安は100行前後、長くて 200行以内が妥当なところだと思いますが、どうでしょうか。＞他の方々。
で、それ以上長くなるような場合には、関数に分けることを考えると。。。
# スクロール等を考慮すれば、ホントは 100行以内を目標にしたいところですが、
# 現実問題かなり厳しいので、目安として私はこれくらいにしています。

回答No.7

jacta

#2です。少し補足しておきます。

> 練習として、他に「これはやっておけ」

というものとして、コメントを一切書かず、コードだけで理解できるように記述する訓練が有効です。

実際の製品には適切なコメントを付けることになるでしょうが、練習段階で中途半端な妥協をしてしまうと十分な訓練になりません。
コメントなしで理解できるコードが書けるようになってからコメントを付けるようにすれば、自ずと必要最小限になりますし、内容も適切なものになりやすいかと思います。

回答No.6

ency

> コメントを一切書かず、コードだけで理解できるように記述する

確かに理想ではあるでしょうね。
でも、現実問題不可能な場合もあると思います。

x = 5; // x に 5 を代入

のような意味のないコメントはつけず、必要最小限にとどめる工夫が必要なのだと思います。

以下、私が気をつけていることです。

1. ひとまとまりの処理は関数化する。
2. 関数名、変数名を工夫してわかりやすい名前にする。
# 私は関数名は動詞を中心とした名前、変数名は名詞を中心とした名前に
# しています。
3. 定数にはマクロまたは enum 値を使う。
4. それでも、どうしても誤解を与えそうな場合は、特に注意が必要な処理の場合にだけ、コメントをつける。

あと、関数にポインタを渡す場合に、IN/OUT 等のコメントを良く見ます。
要するに IN は「関数に値を設定する」、OUTは「関数から値を返す」ということです。
でも私は、こんなコメントよりも IN の方を const 宣言した方が良いと思っています。
そうすれば、関数内で値を書替えようとしたときにコンパイラがエラーをはいてくれますし。

コメントは長い時間が経つと、追加・削除・変更等の修正によってウソになることがよくあります。
つまり、コードは修正されているけども、コメントが修正されていないため、逆に混乱を招いてしまう、ということです。

わかりやすいコーディングにコメントが必要でないとは言いませんが、冗長なコメントは逆にわかりにくくしてしまうことがあるということを覚えておいていただければ良いのではないでしょうか。

回答No.5

noname#15691

> コメントを一切書かず、コードだけで理解できるように記述する

私も同感です。
関数の頭に引数や戻り値や機能の説明は必要ですが、コード中のコメントは結構邪魔です。
コードは保守されてもコメントは保守されないことが多いですし。
また、
x = 5; // xに5を代入
なんて無意味なコメントを平気で書く人もいて、結構迷惑です。

回答No.4

επιστημη（@episteme）

> コメントを一切書かず、コードだけで理解できるように記述する

激しく同意。コードに語らせればコメントでは何をしているか/どうやってるかを書く必要はない。
饒舌なコメントは五月蝿いし、嘘をつくことがある。

回答No.3

5S6

こんな具合にすればいいかと
/***************************************************
　　　GetNum
　　　作成者 : 俺だよ

　　　処理概要
　　　５であるか確かめる

　　　-------------------------------------------
　　　第１引数　　x
　　　型　　　　　int
　　　内容　　　　元になる数値

　　　-------------------------------------------
　　　戻り値
　　　型　　　　　bool

　　　５である　　true
　　　５以外　　　false

***************************************************/
bool HeClass::GetNum(int x)
{
　　　// ５であるか？
　　　if ( x == 5)
　　　{
　　　　　　//５である場合、trueを返す
　　　　　　return true;
　　　}else{
　　　　　　//５でない場合、falseを返す
　　　　　　return false;
　　　}
}

回答No.2

jacta

> 理解しやすいコードを書く練習として、他に「これはやっておけ」
> というのがあれば教えてください。

コメントを一切書かず、コードだけで理解できるように記述する訓練をするのがかなり効果的です。

回答No.1

sha-girl

必ず関数には引数と戻り値の説明と概要を書く。
インデントは統一する。
関数、変数、クラスの命名規則も統一する。
ヘッダにあるクラス、メンバ、関数の定義にも概要を書く。

実際、めんどくさいですが
こうするだけで、客観的にみやすいソースになるはずです。