重複メンテナンス-コードとドキュメント[終了]
-
22-07-2019 - |
質問
これは最高のタイトルではないかもしれません-私の問題を読んだ後に誰かがより良いタイトルを思い付くなら、私はそれを感謝します。また、インターネットではほとんど独学だと前もって言いたいので、知らないツールがたくさんあるかもしれません。
JavaとC#の両方でFlow-Based Programming(FBP)コンセプトを実装するソフトウェアを保守しています。これらのそれぞれについて、次のコードがあります:
- 私のウェブサイト
- SourceForgeファイルリリースシステム(zipファイルまたはjarファイル)
- SourceForge SVN
さらに、次のものに関するバージョン参照と(場合によっては部分的な)説明があります。
- 私のWebサイト(HTML)
- 私のウィキ
- Javadoc
また、私のウェブサイトとSourceForgeには、FBPコードのJavaバージョンの最新バージョンを知る必要がある描画ツールがあります。
すべてが非常に徹底的にクロスリンクされていますが、参照を見逃すことがあります!数日前、私は長い間プロジェクトのSourceForge Newsを更新していないことに気付いたので、やりがいのあることをしなければなりませんでした:-)
これらの乗り物のいくつかはおそらく冗長であることを認識していますが、一般的に、誰が何を見ているのかわかりません。
だから私の質問は、このオーバーヘッドをすべて減らす方法があるかどうかです。 HTML" imbed"関数がいいので、少なくとも最新のバージョン番号を1か所に保存できます。おそらくJavaの相互参照を単純化することはできますが、言語間はさらに改善されますが、ありそうもないと思います。
どんなアイデアでも歓迎します。
解決
ビルド/デプロイプロセスの一部としてドキュメントを更新および保守したいようです。
- ビルド
- 単体テストなど
- ドキュメントのコンパイル
- ビルドのデプロイ
- コンパイルされたドキュメントをデプロイする
それ以外の場合は、尾を追いかけます常に。ドキュメントの展開には、移動先のさまざまなソリューションが必要であることは明らかです(たとえば、Webサイトにコピーする、他の場所にFTPでコピーするなど)
これらすべてに万能薬があるかどうかはわかりません。プロパティファイル/構成ファイルでバージョン番号を維持し、適切な検索/置換を行います。可能な限りコードのドキュメントをコード自体に入れ、それをビルドで前処理します(上記のステップ3)。
doxygen を見た/使用しましたか?これは多言語の要件を処理し、ドキュメントの構築/維持のために確立されています。
他のヒント
ビルド/公開プロセスを自動化する必要があるようです。 O'Reillyのこの記事をしばらく前に読みました。どちらも似たような状況にあるようですか?彼のソリューションはPythonを多用していますが、少なくとも、いくつかのアイデアが得られるかもしれません。