読者です 読者をやめる 読者になる 読者になる

Murga

SE やプログラマの仕事周りに関して個人的に言いたいコト・主張・気持ち。

コードの日本語訳みてえなバカな設計書とか、Excel 方眼紙がなくならない理由について、引用しながら考える

日本の SE 考えてること 設計書 Excel 文化 ストレス 怒り 雑記

まだまとまっていないので、思っていることを、引用しながら書き殴っておく。

自分の立ち位置

  • Excel オンリーな設計工程を止めたい。世に便利なツールがあるならどんどん取り入れたい。
    • だがどんなツールがあるのかは詳しくない (特に Java に適用できるツールに明るくない)。
  • コードの日本語訳状態の詳細設計書は要らない。
    • じゃあ設計書ってどんなことを書いておけば十分なのか分かってない。
    • コードもやり方を統一しておかないといけない場面とかあって、そういうのを表現する全般的な設計書は詳しく書かないとダメかね、とは思う。

詳細設計書という名のゴミ

こちらの記事・コメントを引用しつつ思いをコメント。

彼らはあえて口にしない、あるいは気づいていないが、これには以下のおかしな前提がある。

  1. コードを書くことは基本的に設計を伴わない単純作業である。コードを書き始めるということは、設計が終わったということ。
  2. プログラマーは「詳細設計書」がないとコードが書けない。単純作業をするためのほとんど考えない人たちだからな。
  3. だから要件を理解している上流担当の人が、日本語でプログラムをかくための説明書を作ってあげる必要がある。それが詳細設計書だ。

プログラマーは、それを見てJavaとかのプログラミング言語に一字一句変換していく。この変換作業こそが、彼らのいう「実装」だ。ちなみに、プログラマーが親切心から設計書に書いていないことを実装なんかした日には「設計書と違う、勝手なことをするな」とか怒られかねないので、多少(いや、かなり)変だと思っても設計書に書いてあるままに作ることが多々ある。


SI業界はこの、「詳細設計書+実装」プロセスで長年やってきているが、どうしても良い品質のものが上がってこない。そこで彼らは、どうしたら「設計書」に書いてあることがうまく「コード」に間違いなく変換されていくか、ということを考え始めたたわけだな。
そこでまず、表記揺れがターゲットになった。


俺からすると、どれだけ遠回りしてるんだあんたらは、って感じがしてならない。そんな無駄な苦労するくらいなら、最初からコード書け、と。
EclipseJava書いてみろよ、クラス名間違ってタイプした数秒後には赤線が引かれている。
前のバージョンから何が変わったのか、Excelで正確に表現できるか?変更履歴シートを作る?その履歴人が書くんでしょ?正しいの?SCMのHistory diffするのとどっちが楽なのよ、それは。


もちろん、いきなり何でもかんでもコード書けっていっているわけではない。ただ、コードが得意としている分野を、なぜにそれを最も不得手とする自然言語Excelで無理してやろうとするのか、そこが俺には全くもって解せない。全プロジェクトメンバーの中で、一番スキルレベルの低い人に合わせて作業しているとしか俺には思えないんだがそれは客から金もらって働くProfessionalな仕事の仕方なわけ?
それに、プログラミング能力のない人がプログラムの書き方を、Excelプログラマに指南して、なんかいいことあるか?しかも、なんで、同じことを日本語とJavaにわけて、2人で2回も書いてるのよ?1人が1回Javaで書けばコスト半分だろ?GDつかってコスト1/3ってあんたらちゃんとトータルコスト計算してるのかよ。

全面的に同意。

管理人さんの言ってる詳細設計って、例えば、

要求仕様
 10回helloを表示する

詳細設計
 変数iを宣言
 iを0に初期化
 ループ文でiが10より小さかった真とする
 ループ文の中で”hello\n”という引数を表示関数に渡す
 ループ文の中でiを1加算する

コード
int i;
i=0;
while(i<10){
printf("hello\n");
i=i+1;
}

ってことだと思いますが

そうそう、こういう詳細設計書がバカだなってことよね。

実際に動いているコードと同期がとれているかすら怪しい日本語コードもどきをみてコードのメンテナンスをするくらいなら、最初からコードを理解する気で読んだ方がずっと効率が良いと思っています。

そそそ。

Excelと日本語でしか表現できないから、そこから作成されるコードはツールやプログラミング言語の持っている機能を有効に使わない、ifとforみたいな超基本構文だけで書かれたような、メンテナンスしづらいグダグダなコードが大量に作られます。

これだ。日本語で書けと言われると、どうしても手続き型な書き方になるし、再帰処理とかオブジェクト指向とか、自然言語で適切に表現するにはコストがかかる手法がプログラムには多い。日本語でプログラムを書くのは限界がある。

クソみてえな設計書でも、仕事として書けと言われたからには良いものを書きたいとは思ってる。でも、人間どうしても楽な方に流れがちで、それが悪い方向に働くのが「手続き型ででも設計書書いちゃえばいいんだよな」ってこと。これを良い怠惰の方向、つまりは「こんな設計書なら書かないでコード直接書いた方がいいよね」ってな文化に持って行きたい。

詳細設計書とプログラム設計書を混同した環境(もしくはSIerと)でお仕事してるのかなと思います。
規模が大きいシステムだと後者は見たことがありません。

プログラム仕様書がないとまともに実装ができないのって、アセンブリ言語いじってるとか、コンパイルに膨大な時間がかかった時代とかの話でしょ。Java 以降のシステムではまず不要。

メンテのためにドキュメントが必要なのは当然で、そのために詳細設計書は確かに必要ですね。でもそれはプログラムと同じことを日本語で書いたものである必要はないんですよね。プログラムを日本語ExcelやWordを使って表現してもわかりづらいですし。
結局のところ、SIerが「従来からやってきた詳細設計とはそういうもの」という空気に流されてこれを問題ととらえていない、そして変えようとしていないこと、それからお客さん側も使うかどうかよくわからないままに形だけの設計書を、監査対策等のために求めている、というのが問題だと思っています。
プログラマーの人はコード見ればわかるから、コードを日本語で説明した資料なんかあっても読まないですからね。そういう意味で、本来詳細設計書はプログラムを読む前の知識を得るためのものとして、プログラムに書かれていない、設計上の決まり事やその設計に至った理由とかが書かれているべきだと思っています。

「その決め事、効果あるの?」「そのルール、要る?」って本当に疑うことをしてないんだよね、多くの日本人が。

大体うちの場合、客が納品した設計書一切読まないもんね。本当に何で書いてんのか分からん。

詳細設計書を、コードと同じレベルの詳細さで書くのはナンセンスだと、私は思います。なんのために詳細設計書を書くかが不明確なんだろうと感じます。
一方で別側面の話として、表記の揺れに関しては、それが詳細設計書であろうと、科学論文やプレゼン資料であろうと、テクニカルドキュメントにおいては、表記の揺れるものを書く人間に私は不信感を持ちます。言葉や記号を定義せずにふゎっとドキュメントを書いているんじゃないかと疑ってしまいますね。

日本語力に問題がある人、読み手を考えていないプロには問題があるよね。これは本当に同意。

クラスとの相関関係もインターフェースもコード読み込んで頭を整理するために結局は詳細設計書みたいなものを書くことになるだろうね。
この用途で詳細設計書を書くんなら、コーディングの前に設計のプロセスを持っていく必要はないんですよ。むしろテストが終わって動作が確認できた後に書いたほうが一致度が高い。

全体を把握するための資料はコード書き終わってから作るほうが良い、というのは同意。コーディング前はホントにメモ書きで作り始めて、体系的にまとまった文書は後ででいいでしょ。その文書を今書く理由は何だ?ってこと。

>他のプロジェクトから異動してきたプログラマにいきなりコード見せたら卒倒するよ。
結局これって一言で言うと、ソース読むスキルが低い、もしくはEclipseなどのIDEの習熟度が低いって事ですよ。SIerはIT業界の中でも技術力の観点でみるとかなり低い方だから、そんな所で長く仕事してる人の考え方ですよね。そんなものを下敷きにしてても良いものはできない。
だって、バグが発生した時に設計書見る人いないでしょ?設計書なんか見てバグフィックスできる人見たことないし、それよりもソースと整合性が取れてるかの担保はどうやって取るの? スキルの低い高い関係なく、バグフィックスする時は「ブレーク張ってステップ実行」もしくは「ログ解析」でしょ。どっちにしてもソースを起点としたものです。

JUnitがまともにメンテされてる現場なんかお目にかかった事がないです。
ましてやソースですらない設計書なんかがメンテできてる訳がない。リリース(SIerでいう納品)が過ぎたらゴミ化していくだけのテンポラリーファイルですよ。

一番の問題は、プログラマを含めて関係者のスキルの低さ、これに尽きます。Excelみたいなドキュメントが介在する事が更に(ソース読むなどの)スキル向上を妨げている。
ITのモノを作ろうとしてるなら、もっとソースに精通すべきなんですよ。ソースの読めない・書けないPM、ディレクターはゴミでしかないってのが私の持論です。
事実、スタートアップや伸びてるベンチャーには、「ディレクションしかできません」、「要件を詰めるしか能がありません」なんて人種いないですから。
アメリカではかなり定説化してるみたいですが、「コーディング=設計、実装=ビルド」です。なので、今の時代では実装は一瞬で終わるという事です。

うちのリーダ、設計書しか見られないヤツだなぁ。半日ぐらい設計書だけでバグの原因拾おうと努力して当然見つからなくて重い腰上げてコード読み始めてコード読めなくて翌日俺に聞いてくるパターン。死ねや。

なんでもかんでもアメリカは海外は、ってのも盲目的に聞こえがちだが、要するに「まともなところはこうやってまともな成果を出してる」、ってことで。「能力のない人に合わせて…」って思考が全体的に邪魔してるよね。

そもそも「なんかおかしい、違うよね」と言う状況が改善しない・されない原因の一つに「関係者がそもそもスキルを上げたくない、上げようとしていない」というのもあります。

日本のこの「バカ小学生でも分かるように」って文化は、島国特有のものじゃないかな。資源が限られてて、外部から取り入れるコストが高い生活を長くしてきたから、島の中で、自分たちの力でなんとかしよう、自分たちの力でなんとかできることだけやろう、みたいな方向に考えが働きがち。まさに「ガラパゴス」な状態で、そういう文化しかない環境でそれが育ってきたわけだし。

アメリカやヨーロッパみたいに地続きで色んな資源・文化が入って来やすいと、「能力のある人間が能力を使った仕事をすればいい」「能力のないヤツは入れなきゃいい」ってこともやりやすくて、プログラマとして、SE 的な仕事として、高めていかなきゃいけないところは当然高めていこうぜ?って感覚なんだろうなぁと思慮。

ソフトウェア開発が、建築現場に例えられてしまうこと自体が問題だと思います。それが成立するためには、設計書に従って作れば、製品が完成すると担保されているだけです。ソフトウェア開発はそうじゃない。
私がこの業界でやり始める前は分かりませんが、少なくとも現在のソフトウェア開発は、詳細設計書なんか書いたところで、その通りに実装して完成した試しはありません(ポストによっては、そのように努力したくなる事を否定しませんが、やっぱり不毛だと思います)。

さっき触れた「日本語でプログラムを書く限界」に近くて、ソフトウェア開発の「設計」「製造」は、建築業界の「設計」「製造」とは全く意味が違う。大体プログラムしか書かないのに「製造」って表現するその思考の古さが嫌いで、ぼくはずっと「実装」って呼んでる。それって基盤系の話じゃねえの?ソフトウェアも同じだと思ってナメてるところがあるからいつまで経ってもうまくいかねえんだろ。

ドキュメントはどこまで行ってもドキュメント。
本番サーバでは(ドキュメントを解析して動いてる訳ではなく)、ソース(かそれをビルドしたもの)が動いてて、バグフィックスも機能拡張もソースを元に行われる以上、開発にまつわる全ての事に対して、Eclipseを基軸に考えるのが一番スマートだって話。そこにExcelやWordを介在させればさせるほど余計な脂肪分が増える。
補足資料や開発メモの類のものは必要だろうから、それは残せばいいと思う。ただExcelである必要は1ミリもない。Wikiでもマインドマップでも、写真でも好きなもので残せばいい。

アメリカ人はMS-Officeなんてほとんど使ってなかったぜ。
日本人チームが単なるテンポラリー資料の為だけにExcelに罫線入れて、色付けてキレイなドキュメント作って、会議室予約して、皆のスケジュール押さえて、はいミーティングってやってるうちにとっととモノが出来上がってた。やるとしたら担当者(仕様決定権者)のところに言って仕様を確認するくらい。そこで何らかのメモが必要なのであればnotepadでメモる。

開発者目線では、本当にテキストベースで、かつハイパーリンクで情報同士が結び付けられる仕組みの文書があればそれで十分だよね。Wiki が良いのはそれが両方一気に実現できるシステムであることで、Markdown ももっともっと普及してほしい。

担当者に聞いてメモ書きではい OK、ってのが理想ではあるけど、客側の IT リテラシーがバカみたいに低くて、人類としても底辺なのにのうのうと生きてる輩が日本には多いから、多分無理だろうな。企業として業績や状況を管理するときに、何でもかんでも同じ単位で数値化できた方が楽って視点もあるし、型にハメて会議やって議事録で要件押さえました~っていう、分かりやすいコミットをしていかないと、バカな客は納得しないし、自社内の上層部もプログラムも経営も管理もできねえクソジジイどもだから、この「形から入る」は減らないだろうなぁとは思う。

そこでヒラの自分ができるのは、「型どおりやらなきゃいけないところは自動化する」を徹底するだけ。客向けに Excel で作らされるドキュメントの体裁はテンプレート化しておいて、個人的に Markdown で管理してるメモ書きをテンプレートに穴埋め、会議で余計な話をしなくて済むように決めたい話題だけに絞って文章を手直し、スケジュールを押さえるのは Outlook から参加者の空いている時間を抽出させて選択するだけ。

バカな客はこっちが質問してるのに向こうが質問を作り上げる傾向にある (なんでも自分の尺度に当てはめたがる) ので、ケンカごしで「質問にだけ答えてもらえます?」と怒らせて回答がきたら「そうですかじゃあ次行きます」ってゴリゴリ仕切る。折衝スキルなんか理解力のある相手にしか通用しねえって。

  1. 管理人さんの言っている書類を詳細設計と呼ぶかどうか
  2. 詳細設計と呼ぶと決めた書類にコードを日本語で逐語訳するかどうか
  3. 詳細設計書に他に何を書くか

これら1〜3はプロジェクト毎に決めるべき内容であると考えます。 プロジェクトの最初のほうで、納品先の事情や、プロジェクト予算の都合、むふふな事情を勘案し、合意後、定義しておきます。

とにかく大事なのは定義。変数は宣言して定義するくせに、自分がこれから話の中で使う単語を定義せずに話すバカが多いこと。プロジェクト単位で定義を決めろってことやな。

10年くらい前までは、よくお目にかかったのですが、最近は見なくなりました。
今でもあるんですね。

泣きたい。

コンパイルやテストが簡単に出来ない環境や、そういう状況を長く経験された方は、書類の力を疑わない人も多く、書類のメンテまでが保守開発です!とモチベーションダウンしない人もいます。

古い環境にいた人がそうなのはまだ理解できるけど、「コードは読み書きできないから日本語の文書を書け」って言ってるバカリーダはどうしたらいいんですかね。死に腐ってほしいです。

プログラマ向けとお客様向けの説明が両方詳細設計書でできるっていうあなたの意見の方が、よっぽど冗談に聞こえますけど。

客に「設計書」を見せて話す効果、本当にないと思う。

昔のコーディング用紙かなんかと勘違いしているのか全てを網羅的に書くことが正しいと思い込んでいるのか、不必要な情報が溢れて設計の意図や重要事項が把握できない図や設計書を幾度見たことか。
誰のために何を書くのかが定まっていない現場や会社では特にそう。
そいうところってやたらと体裁には拘りますね。
UML記法を無視した体裁ルールがあったり、チケットすら日報風の定型でないと許さないとか。
そのくせ全体を示す設計書はなく、よく考えられていないコンポーネント図だけあり、仕様は現場リーダーの頭の中なんてね。
定型で書かせることで管理してるつもりになっているのでしょうが、そうさせる合理的な理由がない。
でも声がでかいのですよそういうのに限って。
それと開発者自身も向上心がなく勉強もしてないから改善しようとする意見なんて出てこない。
ただ大変だから(面倒だから)っていうぐらいにしか思ってないから声のでかさに負けてしまう。

ぼくが不満に思ってること、ぼく以外の人も感じてたってことだけで少しは救われる。

設計(design)としての図と言語

設計(design)は図で行うことがある。
建築、機械の分野では、設計というと図だと思う。

論理回路の世界では、(論理)回路図で設計する場合もあるが、言語(HDL)で設計することもある。論理回路設計の世界では、言語で書くことを設計という人達がいる。


抽象的な設計から、具体的な設計へ変換する場合にどういう道具を使うか。
抽象的な設計の妥当性と、具体的な設計の妥当性をどう確認するか。
道具と確認方法がすばらしく、効率的な作業を行うとよい。不必要な文書を作って、あいまいさ、誤解を生んだりすることがある。道具で自動的にやれることを手作業でやって工賃をかせぐという現象もあるかもしれない。

目的が何か、成果が何か、道具が何か、確認方法はどうするのかの視点を明記すれば、議論は収束するのかもしれない。道具がどんどん変化するので、視点も既存の道具に併せて、ずらしていかないといけないのかもしれない。お金の支払いが、道具、視点の変化についていけてない状況で、どのように折り合うかが課題なのかもしれない。

Excel を方眼紙代わりに使う日本人、クレイジーと米国人が驚愕

日-欧米の罫線文化の違い

[欧米] ・タイプライタ文化 ・表は、白地の上にデータを並べるのが基本。タイプライタで清書。 ・だから発想が、表ではなく行-列 ・スプレッドシートは、当初罫線機能なし ・今でも、Excelをプリントアウトすると、デフォルト罫線なし

[日本] ・中身ではなく、形から入るのが好き ・だから、共通書式には、最初から罫線が入っている ・原稿用紙は、1マス1文字の共通書式にすぎない ・和文印刷も和文タイプも、1マス1文字に最適化されている http://www.w3.org/TR/2009/NOTE-jlreq-20090604/ja/ [w3.org]

・罫線があると安心 ・罫線がないと、何を書いていいかわからない ・プランナーの仕事は、罫線を引くこと

海外の IT 企業はエクセル方眼紙使ってないって??何使ってんの?

実は実際のところ、Excel 以外にどんなツールで設計書とか書いてるのか、現場を見てないので知らなかったりする。ネットでの知識だけじゃなくて経験として色んな現場を見たいんだよなぁ。

雑感

なんでも Excel な風潮な治らないと思う。

  • 日本にはネットが繋がらない閉鎖環境が多過ぎる。もしくはネットからツールを落としてきてはいけないとかいうバカな決まりのある環境が多い。
  • ネットがないとか禁止されてるとかで、ツールが入れられないと、当然今あるものの中でなんとかすることを求められる。
  • 大体の現場に標準で入ってて、誰でも読めるツールとなると、MS-Office になってしまう。
  • これが逆に、「誰でも読めるならこのツールで統一しよう」という考え方から Excel を強制されてしまう。
  • 管理とかする側は、Excel だと行数やデータの数とかを集計しやすくて、上層部への報告に求められるデータの収集・解析は楽だったりする。
  • だから、環境的な制限の中、管理する側の都合がマッチしている Excel を使った文書・Excel 方眼紙はなくならない。

ウォーターフォールモデルも治らない。

  • SIer はとにかく「管理」がしたいらしい。
  • 良い物を作るために既存の仕組みを変えることは絶対してくれない。管理する側がよく分かっていなくて、それだと管理できない、と思っているから。
  • もしくは客側が「設計してから実装するものでしょ?」っていう、古くて稚拙な知識しかないのにそれを強制してくるから。もうそんなヤツを相手にする仕事やめようよ…。
  • 明確な「工程」って区切りがあると報告書が作りやすいんだろうな。報告した内容と変わってしまうのも困るので「設計フェーズが終わったら設計書は FIX」みたいなこと言い始めて、不具合修正を経て実装が乖離していく。

仕組みを変える気がない会社にいる以上、何かを改善していくなんて無理な話だ。

もしくは、バカを相手にして、バカに目線を合わせてやる仕事をしている以上、バカには理解できないより良い方法を取り入れていくなんてこと、無理だ。

ネットが繋がってるところで、客を選べる仕事をしたいところだ。

おめえよぉエレベーター乗り込むのに「すみません」って何なんだよ

ストレス

謝るぐらいならエレベーター乗るの止めろバカ。

何を済まないと思ってるんだ?「すみません」ってどういう意味の言葉だと思ってんだ?お前が今そこで「すみません」っていうのは適切か?自分が使う言葉の意味もうちょっと考えろハゲ。

ダレノガレ「ねえ押すのやめなー」

ストレス

電車の乗り方下手なバカ多すぎだろ。

「そう書かれてるソースがあったから真似してコーディングした」は考えていない

日本の SE

新人のコードレビューで「ココはどうしてこういう書き方をしたの?」と聞くと決まって返ってくる答えの第2位。1位は「理由はないです」。1位の奴にはアゴに左フックだけど、2位のこの答えも、理由になっているようでなっていない。この答え方をした時は間違いなくダメ。

他所のクラスでそういう書き方をしているコードがあったとしても、今自分が実装するモノに対して同じように書いていいかは別問題。

だからまず、その場の状況から必要になる実装方針が立てられていないといけない。「ココには既にこういう処理があって、ココを変えるとこういう問題が起こりうる場所で、ココは変更範囲が広くなるからこのやり方を守らざるを得ない」といった状況が把握できていないといけない。

そのクラスの状況から対応方針が立てられてから、それを実現する具体的なコードを書いていく。その時に、「ちょうど自分が思っていた書き方をしている別のクラスがあったから、参考にして書いた」のであれば良い。新人は前半の思考が何もないのに「なんかこれパクったら上手く行きそうだったから」レベルでコピペ駆動開発をしやがる。

自分が完全に分かっていないものはレビューに出すな。自分が分かっていないものを客に提供しようとするな。それは回り回って、「自分が分かんないまんまやってしまったばっかりにバグってデスマ」に陥らないようにするためなのだから。

「負けられない戦いがココにはある」逆に負けられる戦いほとんどない件

嫌いな言葉

負けられる戦いの例を教えてクレメンス。

頭の悪い言葉だなって思って聞いてる。