【解り易い】上手なプログラムを書くには【美しい】

5年後の自分が読んでもわかるように書くことを心がけてます。


んが、余裕がなくなってくるとそうはいかない。

>>790は、何か「醜女の深情け」って感じで泣ける。もしくは「馬鹿の一つ憶え」

大体
> (ry)テーブルはデータなのでプログラム判らないヤツが見てもわかる事もあるしね。
って、お前プログラム解らない奴にプログラムいじらせんなよ。ましてや解った気にさせんな。
プログラム解らない奴にはドキュメント書いて渡せ。

幸い今まで>>790みたいな馬鹿と一緒に仕事をせずにすんでいる我が身の幸福に感謝せず
にはいられないよ。

なんかここ２日ほど異様に盛り上がってるな。switchがキーワードになったのかな。

>903
矛盾している事自体が、重要な情報。
漏れは例え矛盾していようが、コメントはあった方が良いと思う。
ただし過剰なコメント(*)は、明らかに可読性を落とすので要らん。

*例
・1行1コメント
・関数やクラスの定義内での十数行を超える（流れを寸断するような）コメント

なんでswitchが駄目なん？
５種類程度で処理を分岐するには一番シンプルにわかりやすくかけるじゃん。

>>907
矛盾してるコメントはイカン!!

>>907
実務経験ある？
誰かのソース（しかも大規模）を引き継いだ経験とか。

本当に必要なコメントなら十数行でも必要。
むしろ必要。

５種類程度ですむならな。実際は数がどんどん増えていって、しまいにあぼーんだ。

>>790
「テーブル」の中身は具体的には何が入ってるの？
プログラムの動作を制御するためのフラグと関連データが
まとまっているっていう認識であってる？

しまいにあぼーんだ。

著作権がいい加減な国ではソフトウェア産はが育ちません。
日本はその好例。

>910
無論ある。
引継ぎの場合は一層コメントは重要かと。
ソースとコメントの矛盾はバグの目星になるし、「修正が必要な理由」にできる。
（あと品質の目安にもなる。知った所で意味無いけど）
正しく動き、修正の必要が無いなら、コメントは読む必要無いから矛盾してても構わん。

>911
関数やクラスの説明についてのコメントなら、確かに何十行でも必要な場合があるし、
あった方が理解の手助けになる。（長すぎると可読性が落ちるかもしれんが）

しかし、関数やクラスの定義内のコメントなら、(普通は)数行で済むはず。

ってゆーか、関数やクラスの定義内にコメントが必要な時点で
>『他の人が見て用意にソースが追える。』
>『あとでメンテナンスや、機能追加しやすいしやすい。』
がダメダメだろ?

基本的にコメントが間違っていてもプログラムの動作が変わらないわけだし
邪魔なコメントは消せ!

>>917
・・・同意

コメント書かないやつってどんな仕事してるんだ？

いや、マジな話で。

>コメントを書かないやつ

1. 好意的な解釈
すべてのコードに対してunitTestが対応している
使い方はそっちを見てくれ、という事

2. こっちは有り得ないだろう解釈
(自分を含めて)他人が後でそのコードをメンテする事が絶対にないから

3. マゾだから
後で死ぬほど苦労したい

/**
　*　このクラスは別開発チームが担当するXXXクラスを簡単に使うための
　*　ユーティリティー・メソッドを提供する。
　*　将来新バージョンに置き換えられるXXXクラスには変更を加えず、
　*　このクラスに間接的に（委譲等を用いて）機能を実装すること。
　*/

>>919
少し骨だと思うけど、読んでください
>>465-600 辺りをレスします

>>921
ええ。その種のコメントは「いれるべきコメント」だと思いますよ

>>922
それ全部よまねーとお前がどんな仕事してるのかわかんねーのか？
質問の答えとして全部よまなきゃならんと思えないんだが。

お前コメント書いたほうがいいんじゃないか？周りが迷惑してねーか？

>921,922 そのコメント、必要なコメントか?
XXXクラスを使うやつは読まないだろ?

>924
・XXXクラスをメンテする奴にとっては重要な情報。
・XXXクラスを使うだけなら必要ない情報。
・変更加える前に、影響範囲の調査を行わない奴はバカ。
・XXXクラスの影響範囲を調べた時、>921のコメントは見つかる筈。

>>922
全ての関数に例外なくコメント入れてるのって馬鹿じゃないかって思うことはあるね。
doxygenとか使ってたらないと気持ち悪いが。
コメントを入れるのはそれが本当に必要なところだな。
921もそうだしな。

>>923　ああ失礼。
「プログラミングも行うリーダ」です。回答として充分ですか？

>>926　コメントを入れるのはそれが本当に必要なところだな。

その「本当に必要なところ」は人それぞれなんだな。
だから「全部にコメントﾏﾝｾｰ」って規約が出来て・・・（⊃д｀）

まぁ言わんとするとこは分かる。

いまさらだが
>>896が言いたかったのは、
switch(index)
{
　case(0):
　{
　　break;　(2)
　}
}
って書き方はどーよ？ということだろうと言ってみる。

おれはすべてのメソッドに完璧なまでのコメントをいれ
ドキュメント生成ツールの出力みて (・∀・)ﾆﾔﾆﾔ してる。

>926,928
必要無くても書いておかないと、それを見たヴァカがコメントを書かなくても良いと勘違いして
本当に必要なコメントすら書かない事がある。

散々言われてる事だが、コメントは他人が見る事を考えて書くべき。

まったく書かないというのも難しいと思うが、
入門書のような細かなコメントは書かなくていいから。

設計書あるんだからコメントいらねー

ところで。コメントは日本語ですか？

仕事は日本語が通れば日本語。
趣味は英語が多いな。日本語通らなかったり文字コードが異なる環境間で
ソース使いまわしたりするんで。

> ５種類程度ですむならな。実際は数がどんどん増えていって、しまいにあぼーんだ。

数個程度の条件分岐も狂ったようにテーブルにしたら、かえって保守性が落ちる。
PG設計の段階で、うまく切り分けましょう。

コメントは、
１、業務と関係ある（初期値、条件、代入処理、SQL文など）個所
２、ぱっと見で分からなかったり、勘違いし易い個所

に必要だと思うのだがどうよ。
漏れは特に業務処理中心な所は、仕様変更対応の時を考え、
なるべくバカ丁寧に書くようにしている。

特に低レベルな言語ほどコメントの必要性はより高くなる。（業務系の場合）

まぁ、業務ロジックが単純で難易度低い場合や、
個人でやる場合は、どうでも良いと思うが。

手段を説明するコメントは要らない。（ソースを見れば分かる）
ソースを書いた目的や理由を記せ。（ソースを見ても分からん）

仕様に関わるものに関しては、仕様書の参照個所書いてるけどな。

目的や理由の前に誰に読んでもらうかを決定しなければ
書けないと思うよ

難解なアルゴリズムを使うなら、何使ったか書いとけ
もしくはアルゴリズムの解説を残しとけ
手順が何をしているかは分るが、その結果何が起こっているのか判らん。

>>938〜940
先頭のコメントのフォーマットの話だったら
今までのプロジェクトの使いまわしで、必要に応じて改良で良いのでは？
この部分が分かる分からんは、むしろ仕様書の問題だと思うよ。

重要な問題は、ソース中のコメントだと思うが。

>941
手順が分かるのに結果が分からんとはハテ…?

>942
>先頭のコメントのフォーマット
どこの先頭ですか。

>>921
のようなjavadocに吐き出すやつ。
クラスやメソッドの先頭、もしくはファイルの先頭。

先頭の話だとは思えないのだが。
どこかに先頭だと書いてたっけ？

先頭の話とは書いてない。
しかし各メソッド中の各行レベルのコメントについての話ではないでしょ？

先頭でもなく、関数の中でもないのならどこのコメントなんだ？

だから、
各メソッド中の各行レベルのコメント。
手続き型だったら関数の中。

>>943
たとえば、クイックソート、貴方がこのアルゴリズムを知らないとする。
そこにクイックソートの処理があって、これを理解する事ができる？
メジャーアルゴリズムなら知らない方がバカと言えるが、マイナーアルゴリズムは厄介だよ。

「quick sort」とだけコメントに記述すればイイ。保守担当はそのキーワードで検索する
もしくはアルゴリズムをキチンと文書化しておく

オレにはアルゴリズムの説明をプレーンテキストonlyで出来る自信がないな

>>937
ロジックにコメントする香具師は素人。

まともな奴なら、データ構造にコメントする。

コメントはそれが嘘でなくてプログラムに関係しているもので
ある限り書いてあって邪魔ってことはないと思うんだが。

むしろ、勝手な個人の思い込みで書かない方がよくない。

後で保守する人が自分と同レベル（仕様理解度・技術の理解度）
と思ってはいけない。

こんなの仕事でプログラム書いている人にとっては常識だと
思うんだが。

>>952
>>570
貴方、「自分の考え方はもう古いのかも知れない」って自問自答することはないですか？
「常識」という言葉に「価値判断固執」を感じますよ

#もしかして「誰でも保守できるようなプログラムを書くべきだ」と思っていますか？
#それは単純なプログラムばかりだと可能ですけど