version-control - コードと仕様の同期を保つ方法は？-良いツールはありますか

Question

私のチームには、優れたソース管理システムがあり、優れた仕様があります。私が解決したい問題は、コードで仕様を最新に保つ方法です。時間の経過とともに、仕様は古くなり、古くなる傾向があります

仕様を作成する人々はソース管理を嫌う傾向があり、プログラマーはSharePointを嫌う傾向があります。

他の人が使用しているソリューションを聞きたいですか？どこかに幸せな真ん中がありますか？

Answer 1

いいえ。幸せな中間はありません。彼らにはさまざまな対象者がいて、さまざまな目的があります。

アーキテクトおよび仕様ライターとして私が学んだことは次のとおりです。 仕様には長期的な価値はほとんどありません。 それを乗り越えてください。

仕様は、プログラミングを始めるのに適していますが、何をしても時間の経過とともに価値が失われます。仕様の読者は、あまり洞察力のないプログラマーです。それらのプログラマーは、もはや仕様を必要としない、深く知識のあるプログラマーに変身します。

仕様の一部 (特に概要) には、長期的な価値がある場合があります。

仕様の残りの部分に価値がある場合、プログラマーはそれらを最新の状態に保ちます。

うまく機能するのは、コードに埋め込まれたコメントと、それらのコメントを抽出して現在のライブ ドキュメントを生成するツールを使用することです。Java はこれを javadoc で行います。Python はこれをepydocまたはSphinxで行います。C (および C++) はDoxygenを使用します。多くの選択肢があります: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

概要は、元の仕様から取り出して、コードに配置する必要があります。

最終文書を抽出する必要があります。このドキュメントは、仕様の概要とコードの詳細を使用して、仕様を置き換えることができます。

大規模なオーバーホールが必要な場合は、新しい仕様があります。既存の仕様の改訂が必要になる場合があります。出発点は、自動生成された仕様書です。仕様。作成者はそれらから始めて、心ゆくまで追加/変更/削除できます。

Answer 2

ドキュメントを最新の状態に保つには、Sharepoint 以外の wiki が適していると思います。ほとんどの非技術者は wiki の使用方法を理解でき、ほとんどのプログラマーは優れた wiki を喜んで使用します。私の意見では、Sharepoint の wiki とドキュメント管理システムは扱いにくく、使いにくいと思います。

Mediawikiは良い選択です。

私はウィキが本当に好きです。なぜなら、ウィキは採用して維持するのに最も苦痛が少ないからです。それらは自動バージョン管理を提供し、通常は誰でも非常に直感的に使用できます。多くの企業は、Word、Excel、またはその他の種類のドキュメントを使用したいと考えていますが、すべてをオンラインにして、共通のインターフェイスからアクセスできるようにすることが重要です。

Answer 3

あなたが説明していることに正確に対応する特に良い解決策は知りません。一般に、この種のものを実際に同期させている唯一の解決策は、ソース コード (doxygen、Javadoc) からドキュメントを生成するツールです。

Answer 4

ドキュメントとコードの同期を維持するために使用される 1 つの手法は、リテラル プログラミングです。これにより、コードとドキュメントが同じファイルに保持され、プリプロセッサを使用してドキュメントからコンパイル可能なコードが生成されます。私の知る限り、これはDonald Knuthが使用する手法の 1 つです。彼のコードにバグが見つかった場合、彼は喜んでお金を払ってくれます。