詳細仕様書の"詳細"の意味

「プロジェクトひとり」なら無問題なんですけどね。

codingはヨソに任すから詳細仕様書(detail-design)だけお願いされました。
手始めに簡単そうな一部を切り出してざくざくっと書き上げ、
こんなもんでどぉかしら? と渡したのですがウケがよくない。
「こんなんじゃ詳細仕様書になってない」らしぃ orz

えー? コード書くのに必要な情報は全部載せてますよぅ...
どうやら僕の考える詳細仕様書とアチラ様の考えるソレとが違うみたい。

僕的には詳細仕様書は"何をするか"を詳細に書くものなんだが、
先様的には"どう実装するか"を詳細に書くものらしい。

ちょっと待ってくださいよ。
"どう実装するか"を詳細に書くくらいならハナっからコード書きますよ。
"どう実装するか"を詳細に書いちゃったら
ちょっとした実装上の変更/修正で仕様書がウソついちゃうぢゃねぇですか。

投稿日時 : 2008年12月24日 11:22

コメントを追加

# re: 詳細仕様書の"詳細"の意味 2008/12/24 11:32 aetos

「どう実装するか」もある程度書くべきだと思います。
それこそ「プロジェクトひとり」なら要らないんですが、複数人でコーディングを担当すると、書き方がまちまちになってきます。
誰が書いても同じコードになるべきとまでは言いませんが、コーディングポリシーから異なってしまうと後が大変です。
コーディング規約よりももうちょっと設計寄りのところで、クラスの粒度とか、みんなで共有するインターフェイスとか、そんな感じのものは必要だと思います。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 11:33 aetos

あ、コード一行一行に対応するようなものはもちろん要りませんよ。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 11:44 επιστημη

同意です。
実装上のベースラインを示すのは
実装を任すからには呈示せにゃならん思うてます。

なんかねー、「コード一行一行に対応するようなもの」
を欲してるみたいなのね困ったことに。

#「時間計算量はO(logN)に抑えてね」が通じなかった(しょぼーん)。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 11:48 よねけん

こちらが書いているのは詳細仕様書で、
あちらが要求してるのはプログラム仕様書なんでしょうね。

私のところだとドキュメントとして起こすのは詳細仕様書までですね。基本的にはどう実装するかは書きませんが、説明の便宜上、実装に踏み込んだ形で記述することはあります。(××の項目はデータベースのテーブルAのX列から取ってきてね。似たものとしてY列があるけど、そっちから取っちゃダメよ、とか。)

# re: 詳細仕様書の"詳細"の意味 2008/12/24 11:53 ognac

プログラムソースから、プロクラム仕様書を生成するツールが人気を得るのは、その辺りも原因するのかと。
コメントの記述標準に、｢ドキュメントツールを前提としてますので、ツールに合わせて、体裁良く、コメントを書くように」と合ったりします。
私的には本末転倒な気がして、疑問視するのですが、書類の成果物の量が評価対象になるという現実とのギャップか?

洗練されたソースはコメントが不要...というのは作り手の言い分で、上流工程者は、理解されない事があります。
ロジック仕様を要求される現場は時折見かけます。
「理解できない人に見せて、どうなるんだ」という現実より、「こんな成果物を作らせた」という実績が評価される構造かも。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 12:11 aetos

ドキュメント生成ツールは、ライブラリを作っている場合や、改修を引き継いだ場合のための、MSDNのようなリファレンスを作るのには有用だと思いますが、それこそ開発者だけを対象としたドキュメントですね。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 12:39 みきぬ

私は、詳細仕様書には「実装方針」を書くのだと教わりました。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 12:43 まさる

> なんかねー、「コード一行一行に対応するようなもの」
> を欲してるみたいなのね困ったことに。

あー・・・なんか既視感がorz

# re: 詳細仕様書の"詳細"の意味 2008/12/24 12:46 がる

おいらはよく「哲学と実装」って単語を使うですが(哲学は、「UNIXという考え方―その設計思想と哲学 ISBN-13: 978-4274064067 の原題からとってます)。
仕様書には哲学である「なにをしたいか」を書いて、プログラムがそれを実装する(なにをするかが書いてある)、もんだと思ってます。

…って切り分けるとわりと「何を書いて」「何を書かないか」が明確になると、おいらは思ってるのですが。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 12:49 biac

ゎははw …笑って、ゴメン f(^^;

コーダーに渡せばソースコードが出来上がってくるような、いわばコードの日本語訳w が、期待されてるんですね。
そんなもんを書く時間の 1/3 あればコードが完成するわ～っ! …っていうのが本音ですけど、それなりのお代を頂戴できるなら、まぁそういう仕事もアリかな、と。

"どうやって作るか" は開発者のお仕事、っていうか楽しみだと思ってるけど。どうも、それが出来ない、いやそれどころか、苦痛だ、やりたくない、って言う「開発者」が居るのも事実でして。
で、そういう「開発者」に仕事を振るためには、コードの日本語訳w を渡すか、てけとーにやらせておいて後で作りなおすか…

で。やる気はあるんだけど今はまだ上手く出来ないって開発者にとっては、そういう詳細仕様書は良い勉強材料になりそうな気がします。

> #「時間計算量はO(logN)に抑えてね」が通じなかった(しょぼーん)。

ゎははw
うちの社内でも通りませんwww
( …笑いごとぢゃねぇ orz )

# re: 詳細仕様書の"詳細"の意味 2008/12/24 14:13 しゅんた

詳細仕様書というのは、詳細な仕様書・・・
機能を分割してその機能毎の内部ロジックを記述して
それを見ながらプログラマさんが実際にコーディングして
実装すると習いました。
もし詳細仕様書にコードを書いちゃったら、プログラマさん
のお仕事が無くなってしまうような気がします。
違いましたっけ？？

# re: 詳細仕様書の"詳細"の意味 2008/12/24 14:15 επιστημη

> 洗練されたソースはコメントが不要...というのは作り手の言い分で、上流工程者は、理解されない事があります。

本意は
「コードをコメントで説明するな。
　何をしているのか/どうしているのかを
　コードそのものに語らせよ」
だと思うのよ。

それだけの気構えを持って書かれたコードなら
読めるヒトにはコメント不要(書く/読むまでもなし)。
読めないヒトに説明するコメントを添えるのは構わんが、
(追加/変更に伴い)往々にしてコードと乖離するので注意、と。

それにしても
if ( val < 0 ) { /* valが負ならば */
　val = 0; /* valを0にセット */
}
なんつー気の抜けたコメントはどーにかならんもんかね。
こんなコメント屁の役にも立たんのだが、
こんなコメントつけさせる阿呆にも困ったものだ。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 14:39 επιστημη

> 機能毎の内部ロジックを記述して

その内部ロジックは"what:何をするか"を説明してりゃ十分で、
"how:どうするか"を語っては書きすぎだろ? ってことっすね。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 14:49 biac

> こんなコメント屁の役にも立たん

逐語訳コメントって、役に立たんだけならまだしも。
コードが読みにくくなるは、大事なコメントも埋もれるは… (--;

ひょっとして、こんな経過で生み出されたもの? f(^^;

1. 「SE」から渡された詳細仕様書
「××が負ならば、××を0にセット」

2. コードエディタにコピペ。コメントにする。
// ××が負ならば、
// ××を0にセット

3. てけとーな変数名を付けて翻訳したものを、コメントの左側に書く。

※ だから。いつまでも、そんなレベルのままだったら、機械翻訳に置き換えられちまうぞw

# re: 詳細仕様書の"詳細"の意味 2008/12/24 14:51 しゅんた

僕もそう言う考えです。
"what:何をするか"を設計者が、
それを
"how:どうするか"はプログラマさんのお仕事のように
思います。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 15:26 ognac

駆け出しの頃
a = int(b + 0.5) '四捨五入する
と書いて、「処理内容をコメントに書け!」と怒られた記憶が.......
a = int(b + 0.5) ' 0.5加えて、切り捨てる
と書いたら、OKだった......未だに納得できないが、レビュアーの意識レベルの問題が大きいので、プログラマの責任だけではないようです。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 16:30 taka

>なんかねー、「コード一行一行に対応するようなもの」

前のプロジェクトはそんなだったなーｗ

# re: 詳細仕様書の"詳細"の意味 2008/12/24 18:04 みきぬ

コメントには、（whatの意味で）詳細仕様書に書くような内容を記述しとけばいいと思うんですよね。

1. とりあえずメソッドに ToDo コメントを羅列する

// ToDo: まずこれして
// ToDo: それして
// ToDo: あれして
// ToDo: これこれを返す

2. その下に処理を書いていく

3. 書き終わったら、コメントから ToDo を消す

個人的にはこれでいい感じ。

# re: 詳細仕様書の"詳細"の意味 2008/12/24 23:22 インドリ

気持ち分かるピヨ♪
ボクの場合、「何か作って、そうだな・・・基幹業務システムっていうやつ」と言われて、基幹業務システムを要求から運用まで全部やったピヨｗ

# re: オブジェクト指向02 定義2 2008/12/24 23:58 Nm

re: オブジェクト指向02 定義2

# re: 詳細仕様書の"詳細"の意味 2008/12/25 0:00 Jitta

> 3. 書き終わったら、コメントから ToDo を消す
これがされてないと、大変困ります(-o-;

# re: 詳細仕様書の"詳細"の意味 2008/12/25 8:57 biac

TODO コメントは、 Visual Studio が一覧にしてくれるので便利ですね。

> 1. とりあえずメソッドに ToDo コメントを羅列する

私の場合は、テストコード側に TODO を f(^^;

> 2. その下に処理を書いていく

まぁ、一緒。あ、処理じゃなくてテストケースだ f(^^;

> 3. 書き終わったら、コメントから ToDo を消す

"TODO" って文字は消すけど、そのままコメントとして残したり、テストメソッドの Description 属性にしてみたり。

# re: 詳細仕様書の"詳細"の意味 2008/12/26 8:39 επιστημη

> 私の場合は、テストコード側に TODO を f(^^;

あたしゃそのTODOをテスト・メソッド名に。

[Test] void 初期状態ではカウント値0() { .... }
[Test] void incのたびにいっこずつ増える() { ... }

これやりたいがために C++/CLI で Cのテスト書くこともしばしば。

# 良記事紹介：Joel on Software「やさしい機能仕様」 2008/12/26 22:13 まさるblog

良記事紹介：Joel on Software「やさしい機能仕様」

# It's remarkable to go to see this web site and reading the views of all mates regarding this piece of writing, while I am also zealous of getting familiarity. 2018/10/05 0:33 It's remarkable to go to see this web site and rea

It's remarkable to go to see this web site and reading the views of all mates regarding this piece of
writing, while I am also zealous of getting familiarity.

# Hurrah! Finally I got a web site from where I can really take valuable data regarding my study and knowledge. 2018/11/16 17:36 Hurrah! Finally I got a web site from where I can

Hurrah! Finally I got a web site from where I
can really take valuable data regarding my study and knowledge.

# Whats up this is kinda of off topic but I was wanting to know if blogs use WYSIWYG editors or if you have to manually code with HTML. I'm starting a blog soon but have no coding experience so I wanted to get advice from someone with experience. Any help 2019/05/03 23:37 Whats up this is kinda of off topic but I was want

Whats up this is kinda of off topic but I was wanting to know if blogs use WYSIWYG editors or if you have to manually code with HTML.

I'm starting a blog soon but have no coding experience so I wanted to get
advice from someone with experience. Any help would be enormously appreciated!

# Right here is the right webpage for anybody who really wants to understand this topic. You realize so much its almost hard to argue with you (not that I personally would want to…HaHa). You certainly put a brand new spin on a topic that's been discussed 2019/05/13 12:21 Right here is the right webpage for anybody who re

Right here is the right webpage for anybody who really wants to understand this topic.
You realize so much its almost hard to argue with you (not that I personally
would want to…HaHa). You certainly put a brand new spin on a topic that's been discussed for decades.
Great stuff, just great!

# Thanks for finally talking about >詳細仕様書の"詳細"の意味 <Loved it! 2019/07/23 23:49 Thanks for finally talking about >詳細仕様書の"詳

Thanks for finally talking about >詳細仕様書の"詳細"の意味
<Loved it!

# Thanks for finally talking about >詳細仕様書の"詳細"の意味 <Loved it! 2019/07/23 23:50 Thanks for finally talking about >詳細仕様書の"詳

Thanks for finally talking about >詳細仕様書の"詳細"の意味
<Loved it!

# Thanks for finally talking about >詳細仕様書の"詳細"の意味 <Loved it! 2019/07/23 23:51 Thanks for finally talking about >詳細仕様書の"詳

Thanks for finally talking about >詳細仕様書の"詳細"の意味
<Loved it!

# Thanks for finally talking about >詳細仕様書の"詳細"の意味 <Loved it! 2019/07/23 23:52 Thanks for finally talking about >詳細仕様書の"詳

Thanks for finally talking about >詳細仕様書の"詳細"の意味
<Loved it!

# qlMJTBKFEgpGh 2021/07/03 2:45 https://amzn.to/365xyVY

Louis Vuitton Handbags On Sale Louis Vuitton Handbags On Sale

# If some one wishes expert view concerning running a blog afterward i suggest him/her to go to see this website, Keep up the good job. 2021/08/23 14:41 If some one wishes expert view concerning running

If some one wishes expert view concerning running a blog
afterward i suggest him/her to go to see this website, Keep up the
good job.

# If some one wishes expert view concerning running a blog afterward i suggest him/her to go to see this website, Keep up the good job. 2021/08/23 14:42 If some one wishes expert view concerning running

If some one wishes expert view concerning running a blog
afterward i suggest him/her to go to see this website, Keep up the
good job.

# If some one wishes expert view concerning running a blog afterward i suggest him/her to go to see this website, Keep up the good job. 2021/08/23 14:43 If some one wishes expert view concerning running

If some one wishes expert view concerning running a blog
afterward i suggest him/her to go to see this website, Keep up the
good job.

# If some one wishes expert view concerning running a blog afterward i suggest him/her to go to see this website, Keep up the good job. 2021/08/23 14:44 If some one wishes expert view concerning running

If some one wishes expert view concerning running a blog
afterward i suggest him/her to go to see this website, Keep up the
good job.

# It is not my first time to pay a quick visit this website, i am browsing this site dailly and get fastidious information from here daily. 2021/08/24 2:10 It is not my first time to pay a quick visit this

It is not my first time to pay a quick visit this website, i am browsing this site dailly and get fastidious information from here daily.

# This is the perfect website for anyone who wants to find out about this topic. You know so much its almost tough to argue with you (not that I actually would want to…HaHa). You definitely put a fresh spin on a subject which has been discussed for decade 2021/08/25 1:44 This is the perfect website for anyone who wants t

This is the perfect website for anyone who wants to find
out about this topic. You know so much its almost tough to argue with you (not that I actually
would want to…HaHa). You definitely put a fresh
spin on a subject which has been discussed for decades.
Wonderful stuff, just wonderful!

# This is the perfect website for anyone who wants to find out about this topic. You know so much its almost tough to argue with you (not that I actually would want to…HaHa). You definitely put a fresh spin on a subject which has been discussed for decade 2021/08/25 1:45 This is the perfect website for anyone who wants t

# This is the perfect website for anyone who wants to find out about this topic. You know so much its almost tough to argue with you (not that I actually would want to…HaHa). You definitely put a fresh spin on a subject which has been discussed for decade 2021/08/25 1:46 This is the perfect website for anyone who wants t

# This is the perfect website for anyone who wants to find out about this topic. You know so much its almost tough to argue with you (not that I actually would want to…HaHa). You definitely put a fresh spin on a subject which has been discussed for decade 2021/08/25 1:47 This is the perfect website for anyone who wants t

# First off I want to say great blog! I had a quick question that I'd like to ask if you do not mind. I was curious to know how you center yourself and clear your head prior to writing. I've had difficulty clearing my thoughts in getting my ideas out. I t 2021/08/26 5:16 First off I want to say great blog! I had a quick

First off I want to say great blog! I had a quick question that I'd like to ask if
you do not mind. I was curious to know how you center yourself and clear your head
prior to writing. I've had difficulty clearing my thoughts in getting my
ideas out. I truly do enjoy writing but it just seems like the first 10 to 15 minutes
are generally wasted just trying to figure out how to begin. Any ideas or
tips? Thanks!

# Hi! Do you know if they make any plugins to assist with Search Engine Optimization? I'm trying to get my blog to rank for some targeted keywords but I'm not seeing very good results. If you know of any please share. Cheers! 2021/09/01 20:42 Hi! Do you know if they make any plugins to assist

Hi! Do you know if they make any plugins to assist with Search Engine Optimization? I'm trying to get my blog to rank
for some targeted keywords but I'm not seeing very good results.
If you know of any please share. Cheers!

# Hi! Do you know if they make any plugins to assist with Search Engine Optimization? I'm trying to get my blog to rank for some targeted keywords but I'm not seeing very good results. If you know of any please share. Cheers! 2021/09/01 20:43 Hi! Do you know if they make any plugins to assist

# Hi! Do you know if they make any plugins to assist with Search Engine Optimization? I'm trying to get my blog to rank for some targeted keywords but I'm not seeing very good results. If you know of any please share. Cheers! 2021/09/01 20:44 Hi! Do you know if they make any plugins to assist

# Hi! Do you know if they make any plugins to assist with Search Engine Optimization? I'm trying to get my blog to rank for some targeted keywords but I'm not seeing very good results. If you know of any please share. Cheers! 2021/09/01 20:45 Hi! Do you know if they make any plugins to assist

# I enjoy reading through an article that will make people think. Also, many thanks for permitting me to comment! 2021/09/04 17:38 I enjoy reading through an article that will make

I enjoy reading through an article that will make people think.
Also, many thanks for permitting me to comment!

# I enjoy reading through an article that will make people think. Also, many thanks for permitting me to comment! 2021/09/04 17:39 I enjoy reading through an article that will make

I enjoy reading through an article that will make people think.
Also, many thanks for permitting me to comment!

# I enjoy reading through an article that will make people think. Also, many thanks for permitting me to comment! 2021/09/04 17:40 I enjoy reading through an article that will make

I enjoy reading through an article that will make people think.
Also, many thanks for permitting me to comment!

# I loved as much as you'll receive carried out right here. The sketch is attractive, your authored subject matter stylish. nonetheless, you command get got an shakiness over that you wish be delivering the following. unwell unquestionably come more forme 2021/09/05 23:03 I loved as much as you'll receive carried out righ

I loved as much as you'll receive carried out right here.
The sketch is attractive, your authored subject matter stylish.

nonetheless, you command get got an shakiness over that you wish be
delivering the following. unwell unquestionably come more formerly again as exactly the same nearly very often inside
case you shield this increase.

# When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here. 2021/10/27 5:10 When some one searches for his vital thing, thus h

When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here.

# When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here. 2021/10/27 5:11 When some one searches for his vital thing, thus h

When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here.

# When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here. 2021/10/27 5:12 When some one searches for his vital thing, thus h

When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here.

# When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here. 2021/10/27 5:13 When some one searches for his vital thing, thus h

When some one searches for his vital thing, thus he/she wishes to be available that in detail, therefore that thing is maintained over here.

タイトル		タイトルを入力してください
名前		名前を入力してください
URL
コメントコメントを入力してください
名前をブラウザに記憶する

東方算程譚

目次

Blog 利用状況

ニュース

記事カテゴリ

書庫

日記カテゴリ