ファイルフォーマットの文書化

file import specifications

私たちは、定義したカスタムファイルフォーマットから多くの入力を受け取るアプリケーションを開発しています。 入力ファイルはサードパーティによって開発されたアプリケーションによって作成されているので、当然のことながら私たちのプログラムへの許容可能な入力と不可能な入力を効果的に通信できる必要があります。

ファイルには10行のヘッダー部分があり、各行は異なるメタ情報を表し、その後に改行と「フッター」が続きます。 フッターには情報の内容が含まれています。 ヘッダーはかなりわかりやすいですが、フッターに到達すると、各行には事前定義された文字オフセットで始まる複数のフィールドがあります。

他の誰かが似たような状況にあり、これらの種類のファイル形式を文書化する方法についていくつかのヒントを提供できるかどうか私は思っていました。 このファイル仕様のドキュメンテーションはたぶんWiki上に表示されるでしょうが、私はそれがハードコピーマニュアルでの出版にも適していることを望みます。

  2  0


ベストアンサー

https://stackoverflow.com/questions/1276752/documenting-a-file-format/1276788#1276788[mouviciel]およびhttps://stackoverflow.com/questions/1276752/documenting-a-file-format/からの回答1276790#1276790[Bravax]が役に立ちました。 一方はあなたのドキュメントがあなたのファイルフォーマットに関して提供するべきであるいくつかの技術的な側面でもう一方を表示します。

私はこの問題の両端にいました(ファイルフォーマット仕様の作成/使用)。 これは私がドキュメンテーションを読んでいたときに私が欲しかったもののリストです。

  • ファイル形式の視覚的表現

  • ファイルフォーマットの例を示します。 ドキュメント作成者が正当だと考えるファイルの例を含めることは正当ではありますが、役に立ちません。

  • あなたのドキュメンテーションが電子的であるならば、それを関連部分にハイパーリンクさせることは役に立ちます。

  • ファイル形式を正当化する。 これは、単に盲目的に仕様に従うのではなく、自分が何かをしているのを理解するのに役立ちます。

技術面では、後で追加できるようにファイル形式内に柔軟性を作成します。 ヘッダを持つことは素晴らしいアイディアです。 将来、他のメタ属性を追加する必要がある場合に備えて、「ヘッダーの長さ」属性とともにバージョン番号ヘッダー行を作成することもできます。

3


あなたの質問の2番目の段落はあなたのインターフェース文書への良い入門書でしょう。

それから、ヘッダー用とフッター用の2つのセクションを追加します。

ヘッダーセクションには、各行に何が期待されているかの説明が含まれています。

foorterセクションは、各行が1つのフィールドを説明し、列が次のとおりであるテーブルです。

  • フィールド名、

  • オフセット、

  • 長さ

  • 目的

1


私はこれまでおおよそこれに似たXMLスキーマを書くのを手伝ってきました。

私のアドバイスは、ファイルがどのように構成されているのかを正確に文書化することに絶対的に明示的になることなので、あいまいさはありません。

だからあなたが考慮する必要があるものは以下のとおりです。

  • 間隔

  • 行末マーカー

  • ファイルの終わりマーカー

  • ファイルの各領域に使用できる文字

  • 各エリアの許容値範囲

  • 必要なエンコーディング、および使用する方法/アルゴリズム。

理想的には、ファイルを検証するために、第三者に渡すための検証プログラムを書くことができます。 そのため、問題が発生する可能性を最小限に抑えることができます。

1


タイトルとURLをコピーしました