COBOLソース調査時の入出力データの説明文の注意事項

今の私の仕事は、メインフレーム（富士通汎用機）、COBOL、EASY、JCLで書かれた
オブジェクトをJavaのオープン系システムに書き換えること。

その中で汎用機の仕様解析をしています。
外部設計書とか内部設計書はあったりなかったり、
あってもソースと内容が違ったり。
そんな仕事を開発経験1年ぐらいの私に任されています。
（運用経験4年ぐらい）

そんな中でソースを見ながら、COBOLが読めない人にも分かるように
説明文を書いているのですが、
項目名（COBOL名称）が、F0CFG89N-REC-KBNだとします。

で、COBOLは一般的に入力データはDK-100、出力データはDK-200と記載すると思うんです。
この場合、項目はDK-100-XXXXXに統一した方が分かりやすいですね。
だから、上の例だとDK100-REC-KBNです。

設計書の記載は基準を作ってそれを守るべき！

という当たり前のことなんですが、
ソース解析をしてコメント、説明文を書いているとついつい忘れがちです。

PERFOMEは呼び出し、GOTOは移動

PERFOME文は処理を呼び出して、呼び出し後にどうセクションの光景処理に移る。
GOTOが、その処理に移動する。（セクションの途中でも）

人にソースを説明するときは、上から読めばいいというわけではない。

たとえば、

レコードを読み込む。
レコードが無い場合は終了フラグに１を設定する。
レコード内容をワークエリアに書き込む。
レコードカウントを１加算する。

という処理の場合、上から説明するより、

レコード内容をワークエリアに書き込む。
レコードカウントを１加算する。
レコードが無い場合は終了フラグに１を設定する。

とした方が伝わりやすいです。
ただ、レコードが0件の場合は元々の順序で説明した方が分かりやすいです。

インターフェース設計書の「N」と「X」

結構、分からない人が多いようです。
Nは数値、Xは文字

で、「なんでintとかで書かないんですか」と経験の浅い人（私もですが）
とか聞かれたりします。
Intだと10桁までしか表記できないから、IO設計書だとXかNで書くわけです。
売り上げ明細NOとかだと10桁超えて。Long型になったりします。

加えて、外部設計書はお客様提出成果物であり、説明義務があるので、
数値型か文字型かだけしか記載しなかったりします。

インターフェース設計書とデータベース項目定義書

何故、別々にあるか理解できない新人さんがいました（新人さんだから当たり前ですが）

インターフェース設計書は、Jabaとかのオブジェクトが、外部や他のシステムとデータを
やりとりするときの仕様書、説明書です。
この項目は数値型で１０バイトですよー、とか。

データベース設計書はそのシステムの中で、どう値を保存するかの設計書です。
インターフェース設計書に書かれた項目を受け取って、
それを条件にそって、別の項目をシステム内部で作成したときなどは、
その項目はデータベースの中に格納したりします。
この項目はIO設計ではありません。
IO設計書はあくまでシステム間でやりとりする項目の仕様書なので。

一つのシステムの中で管理する項目はDBで管理するのが、一般的で、
この説明書がデータベース項目定義書、仕様書です。

javaができてCOBOLができないわけがない

COBOLは少ないデータ資源を効果的に活用できるすばらしい言語です。
簡単な入門書を一冊、三回ぐらい読めば、後は現場の中で分からないことを
ぐぐったり、本で調べれば、すぐにできるようになります。
是非、勉強してください、と新人さんに伝えたい。

明日の目標とすること

今日、よく分からないまま終わったソースをもう一度読み直す。
それで分からなかったらベテランさんに聞いてみる。
調査資料は自分以外の人が見ても分かるように、見やすいように
基準を、自分ルールを厳密に決めて書く。
一つの作業、不明点に時間がかかりそうになったら、
やり方を考え直すかベテランさんに相談する。
新人さんに教えるときはいきなり話さないでどう話せば分かりやすいか
考えてから話す。