AUTOSAR CountdownAdvent Calendar 2022

塩谷敦子、菊池百代「ソフトウェアドキュメンテーション」１１個の良いこと５つの経験則図(29)

Last updated at 2024-07-11Posted at 2019-07-24

「ソフトウェアドキュメンテーション」塩谷敦子、菊池百代, デンソークリエイト, 1999, ISBN4-931392-04-4 第二版, 2000
を拝見している。
https://bookmeter.com/books/7984303

11個の良いいことが書いてある。それぞれのよいことの理解、事例を付記してみる。

1　設計

・解説書からの脱却

source codeは設計です。論理回路言語のVerilogHDLなどでは、ソースコードが設計で、回路図が実装です。計算機言語でもソースコードが設計で、機械語が実装です。１対１対応しているわけではないことに注意してください。compile option, link optionで様々な機械語に実装可能です。
source codeの注釈(comment)が、関数の日本語訳になっていたり、解説になっていて、source codeを治す度に、注釈も直さなくてはいけないのは、できるだけ避けたい。

設計は図で書いても、プログラミング言語のソースコードで書いてもよい。

図を使って分析・設計すればこんなに簡単。安全(11), 図(11) https://qiita.com/kaizen_nagoya/items/6347eb55b2812d745549

設計図(12) 表はいつ(when)書く、何を(what)書く、どうやって(how)書く。仮説(71) https://qiita.com/kaizen_nagoya/items/7fddfa5d8bfb5a947db8

2 構造

・ドキュメントの構造化

複数のライブラリ(source code付き、なしのどちらの場合も）を利用する場合に、両方の構造を分析し、どう組み合わせるとよいかを検討するとよい。
source code付きの場合に、手を入れる（入れてもらう）かどうかも、構造化の方針による。
覆(rapper)を作るだけにするか、命名規則をどうするか、構造化の方針によって違うかも。

3

・文章の構造化

構造化したsource codeには、設計図以外には、仕様書、設計書など他の文書があまり必要ないというのが経験則。
COBOLのように、仕様の一部である環境を記述する習慣が、他の言語では規定でないのは残念。
他の言語の良いところは見習い、ソースコードの最初に仕様と環境等の制約条件を、その次に設計の基本的な構造と必要な図へのURL等を書くとよい。

p.9

4

・目次を決めること　=　仕様・設計の項目を決め、全体像を明らかにすること

source codeに仕様・設計の項目の記述をし、全体像を明らかにするとよい。
場合によっては、仕様記述言語、設計記述言語（プログラミング言語）で書くとよい。
仕様、設計は自然言語の記述をなくすとよい。
図等のXMLファイルをソースコードに注釈としてつけても良い。

5

・タイトルと内容の一致

関数名と処理の内容が違ったら、名前の意味がない。
関数機能を機密にし、source codeを公開しない場合はこの限りではない。
関数名は標題(title)であり、機密上の理由がないかぎり、処理の中身を意味する言葉にする。

関数機能は、試験プログラムによって、その機能を類推できる可能性がある。
隠せば、覗きたくなるといういたちごっこをするより、open sourceにするのも一つの手かも。

6

・目的や意味をあきらかにすること＝優れた開発用ドキュメントの条件

関数名の前後に書く注釈は、開発目的・意味と連動した、関数の目的・意味のうち、関数名では表現しきれていないことを記述するとよい。

p.10

7

・記述視点の統一

設計(source code)の記述視点は、入力、処理、出力、操作者、保守者など、いくつか考えられる。
操作者も、子供、高齢者、障碍者など、いくつもの視点が必要である。
それらを体系的に整理することが統一(integlation)であって、視点を一つにすることが統一ではない。

8

・用語の整理と定義

自然言語には、正しいという概念を適用すると矛盾だらけになり立ち往生する。
正しいという概念が必要な場合は、論理仕様記述言語で記述するとよい。
用語は言語仕様で定義している。
無駄な用語を使わずに、無駄な定義を少なくすることが、体系を単純にし、破綻を防ぐ可能性がある。

利害関係者の間では、用語が逆転していることもしばしばである。
関係者の間の用語の整理と定義の矛盾を確認するとよい。

p11

9

・図の意味の明示

状態遷移図(state chart)、時系列図(sequence chart)、刻時図(timing chart)、利用事例図(use case chart)などの図や、目標構造記述(GSN: Goal Structuring Notation)などと、Source Code上の用語の違いなどで誤解が生じないようにするとよい。

10

・改定履歴

Github, Gitlab, Bitbucketなどのgit系を利用していれば、改定履歴の保存は容易である。
一貫性の確認も、元に戻すことができるのであるから、プログラミングするのはむづかしくない。

Github, Gitlab, Bitbucketのシステムのwikiの機能も改定履歴機能があり、元に戻すことができる。

課題は、改定者の意図が分かるようにする工夫である。
小さな事業では、記号、略号でも改定者の意図はわかるかもしれない。
大きな事業では、いろいろな立場の人が関わると、改定者の意図が伝わらないかもしれない。

11

・表記法の工夫

改定履歴で記載したように、表記法の工夫で解決する課題と、仕様記述言語、表記言語など複数の言語を採用することによって解決する課題とがあるかもしれない。

表記法上の工夫は、手で行わずに、道具にするとよい。

安全工学シンポジウム2019

安全分析の図的表現方法、及び設計文書と親和性の高いツールの提案
　ガイオ・テクノロジー（株）技術開発本部技術戦略室技術戦略グループ　田中伸明,　名古屋市工業研究所　小川清
https://www.gaio.co.jp/newslist/anzen_org2019/

課題・経験則

ドキュメンテーション

「文書化」または「文書」ではなぜ駄目なんでしょう。

文書の評価の一つに、重要な言葉の占める単語と文字数の関係についての議論があります。

経験則１　頻出する重要語は、なるべく短く

検討の対象として「ソフトウェア」と「ドキュメンテーション」がある。

ソフトウェアは、軟件と書くと怒る人がいるし、算譜と書くと、異論を唱える人がいて、やっかい。

ドキュメンテーションは、文書化か文書でいい。

なぜ、カタカナ語を使い、不必要に文字数を増やすのかが疑問。

経験則２　カタカナ語はその分野の専門用語だけに限定し、他の分野の用語では用いない。

仕様書、設計書

p.4

ソフトウェアの開発は、仕様書や設計書を作成することを中心に進めていくべきです。

おかしいかも、少し手直ししてみる。

ソフトウェアの開発は、仕様や設計を中心に進めていくべきです。

市場・顧客視点が抜けている。システムの制約も抜けている。

ソフトウェアの開発は、システムの制約と市場・顧客の動向にもとづいた仕様や設計を中心に進めていくべきです。

分業すると、仕様書や、設計書を埋めることが仕事だと思い、市場、顧客、システム制約に焦点を絞らない可能性があります。

経験則3 三方よし、三つ以上の立場で見直す。

開発工程

落水模型(water fall model)にもとづいて、それぞれの工程に文書を作っても、
実際は、20年くらい前から機敏(agile)が主流だったと感じている。

無駄な工程、無駄な文書を減らす工夫をまず語るのがよい。

経験則4 良くすることを考える前に、減らすことを考えてみる

1.3　開発用ドキュメンテーションの指針

いいことをいっぱい書いている。開発指針（source codeを含む）であるとなおよい。
ドキュメンテーションという言葉はいらない。
すべてdocumentなのだから。allを省略するのは論理的かも。

経験則5 相似な構造を探す

参考資料(reference)

「外来語」言い換え提案
https://www2.ninjal.ac.jp/gairaigo/

参考資料 on Qiita

まぎらわしい、間違えやすい、行き違いの多い略号worst 10(候補24)
https://qiita.com/kaizen_nagoya/items/0bff5dbb72208053489b

仮説(88)用語の衝突(用語・用例募集中)
https://qiita.com/kaizen_nagoya/items/6a8eb7ffaa45eeb16624

プログラマが知っているとよい英単語の語源
https://qiita.com/kaizen_nagoya/items/9de6d47c47e2c211222b

プログラマが心がけるとよい文章の書き方
https://qiita.com/kaizen_nagoya/items/af1e6207ccaa063dafb8

「ソフトウェア品質シンポジウムでBest Paper Effective Awardを受賞するコツ？」に付け加えたい5つのこと
https://qiita.com/kaizen_nagoya/items/70a53f19d95d571a0e48

塩谷敦子、菊池百代「ソフトウェアドキュメンテーション」１１個の良いこと５つの経験則図(29)

1　設計

2 構造

3

4

5

6

7

8

9

10

11

課題・経験則

ドキュメンテーション

経験則１　頻出する重要語は、なるべく短く

経験則２　カタカナ語はその分野の専門用語だけに限定し、他の分野の用語では用いない。

仕様書、設計書

経験則3 三方よし、三つ以上の立場で見直す。

開発工程

経験則4 良くすることを考える前に、減らすことを考えてみる

経験則5 相似な構造を探す

参考資料(reference)

参考資料 on Qiita

関連資料

自己記事一覧

文書履歴(document history)

最後までおよみいただきありがとうございました。

Thank you very much for reading to the last sentence.

塩谷敦子、菊池百代「ソフトウェアドキュメンテーション」１１個の良いこと５つの経験則 図(29)

1 設計

2 構造

3

4

5

6

7

8

9

10

11

課題・経験則

ドキュメンテーション

経験則１ 頻出する重要語は、なるべく短く

経験則２ カタカナ語はその分野の専門用語だけに限定し、他の分野の用語では用いない。

仕様書、設計書

経験則3 三方よし、三つ以上の立場で見直す。

開発工程

経験則4 良くすることを考える前に、減らすことを考えてみる

経験則5 相似な構造を探す

参考資料(reference)

参考資料 on Qiita

関連資料

自己記事一覧

文書履歴(document history)

最後までおよみいただきありがとうございました。

Thank you very much for reading to the last sentence.

塩谷敦子、菊池百代「ソフトウェアドキュメンテーション」１１個の良いこと５つの経験則図(29)

1　設計

経験則１　頻出する重要語は、なるべく短く

経験則２　カタカナ語はその分野の専門用語だけに限定し、他の分野の用語では用いない。