タグ付けされた質問 「documentation」

ドメイン駆動設計の中核は、会話、コード、データベーススキーマ、UI、テストなど、システム全体でユビキタス言語を一貫して使用することです。 私は、国際標準化機構によって定義された、確立されたドメイン言語がすでに存在するプロジェクトに関与しています。 ただし、私たちが行っている作業はパブリックWebサイトのためのものであり、ドメインの「正しい」用語は、一般の人々が通常それらを使用して理解する方法とは限りません。 現時点で使用している妥協点は、UIコンポーネントを参照する承認基準を除き、どこでも「公式」の用語を使用することです。ここでは、非公式の名前を使用しています。 これは合理的なアプローチのように見えますか？

10 documentation  domain-specific-languages 

自然言語の形式張らない性質のために、曖昧さのない完全なソフトウェア仕様を英語で書くことはおそらく不可能だと私には思えます。したがって、本当に明確な仕様には、正式に指定された言語で書かれたコードを含める必要があります。 これは既知の結果ですか、それとも何か不足していますか？

10 documentation  specifications 

私は、記述されたコードが自明であり、本のように読まれるべきであるという考え方を持っている開発者の1人です。 ただし、他の人が使用するライブラリコードを開発するときは、できるだけ多くのドキュメントをヘッダーファイルに入れるようにしています。これは質問を持ち出します：非公開のドキュメント化方法は時間の価値さえありますか？彼らはそれらを直接使用することはありませんが、実際には使用できません。同時に（しぶしぶながら）未加工のコードを配布すると、これらの非パブリックメソッドが表示され、説明が必要になる場合があります。 皆さんが旅行中に見たり使用したりする基準や慣行を探しているだけです。

10 c++  documentation 

ここで何が質問されているのかを理解することは困難です。この質問は、あいまいで、あいまいで、不完全で、過度に広い、または修辞的であり、現在の形では合理的に回答することができません。再開できるようにこの質問を明確にするヘルプについては、ヘルプセンターに アクセスしてください。 8年前休業。 小さなイテレーションが好きです。単体テストが好きです。コードレビューが好きです。私が気に入らないのは、ドキュメントがほとんどないかまったくないところから始めることです。私はこれで一人ですか？プロセスについて誤解しているだけですか？ どんな考えでもいただければ幸いです。

10 agile  documentation  methodology 

閉まっている。この質問はトピックから外れています。現在、回答を受け付けていません。 この質問を改善してみませんか？ 質問を更新して、ソフトウェアエンジニアリングスタック交換のトピックになるようにします。 6年前休業。 私たちの社内ソフトウェアは多くのユーザーに使用されており、トレーニング部門はエンドユーザーのドキュメント形式のヒントを求めてきました。 トレーニング部門がインスピレーションを得るために使用するソフトウェアエンドユーザードキュメントの良い例や、良いアドバイスがあるサイトがどこにあるか知っていますか？ これはこの質問に似ていますが、技術者以外のユーザーが使用するエンドユーザードキュメントを探しています。

10 design  documentation  users 

のコードをドキュメント化しましたが、コードdoxygenが提供するデフォルトのHTMLは必要ありません。（GNOMEのように）カスタムCSS、ヘッダー、フッターなどを提供することでカスタマイズできること、そして一般的なPHPコードをファイルに追加してとして保存するように指示する方法を.php知っていますが、それは本当に望んでいることではありません。 私が欲しいのはMSDNのような出力です。私はそれを本当に説明することはできません。私の質問は、テンプレートのようなものでdoxygenを使用してこれは可能ですか、それともXMLを出力して別のプログラムで解析する必要がありますか（私は書いてもかまわないでしょう）。

10 documentation  templates  documentation-generation 

アルゴリズムのドキュメントには何を含める必要があるのでしょうか。従うべき適切なガイドラインが見つかりません。含めることを心に留めています アルゴリズムの要約 アルゴリズムの説明 フローチャート 疑似コード 入力データセットのサンプル（複数） 出力データ 単体テスト 実験 クライアントは次のような文書を要求します。自社の数値に自信を持たせるとともに、プロセスを見込み顧客に説明して、計算をチェックおよび検証するための手順を踏んでいることを顧客に説明します。 そのようなドキュメントはどのように見えますか？（PDFの例） このドキュメントに何を追加しますか？ 私が列挙したものはそれで良いですか、またはこれはどういうわけか異なって文書化されるべきですか？ このようなドキュメントサンプルをGoogleでどのように検索しますか？

10 java  php  algorithms  documentation  sql 

ソフトウェア開発に関連するドキュメントはたくさんあります。これらには、要件、設計ドキュメント、外部PDF、顧客ファイル、テスト手順などが含まれます。現在、これらのドキュメントは場所（wiki、「ネットワーク上の場所」、ローカル開発者のハードドライブ（！）、そしてさらに悪い場所）。 それらを追跡する最良の方法は何ですか？開発にはビジュアルスタジオ（2010）を使用しており、プロジェクトに非開発者が実際にいないため、それらをVS "ソリューション"内に保存して、ソース管理され、すべての開発者が普遍的にアクセスできるようにします。 ただし、VSは実際にこれを行うように構築されていないようです。ドキュメントファイルを編集する場合、ビルドプロパティが[なし]、[コピーしない]でセットアップされている場合でも、VSはソフトウェアを再構築してから再度実行する必要があります。ソリューション内に「ドキュメントプロジェクト」を作成する方法はありません。（これには空のC＃プロジェクトを使用します）。Visual StudioとWord / Excelフラットは、ソース管理がうまく機能しません。チェックインされたファイルを表示して、最初にファイルを閉じてプロジェクトに移動し、変更を行う前に手動でチェックアウトしないと、変更を行うことはできません。遅くても退屈な作業です。 とにかくこれは私たちのチームが考え出した最高のものですが、私は本当にもっと良い（無料の）ソリューションがあったらいいのにと思います。

10 version-control  documentation 

別のプログラマの見直しながら、正規分布のCDFを計算する関数の実装を、私が作っ提案 Pythonの組み込み関数または使用scipyのダウンロード、共通の科学的なライブラリを実装全体を置き換えるのいずれかにします。 別のプログラマーは、彼らのドキュメンテーションにおいていかなる正確性の保証math.erfc()もscipy.stats.norm.cdf()提供もしないことを指摘しました。したがって、（尊重されたソースから取得され、エラー範囲が文書化されていた）近似アルゴリズムの置き換えについては、さらに注意する必要があります。 正直なところ、組み込み関数やライブラリー関数の正確さと正確さを疑うという考えは、私の心を超えたことはありませんでした。結局、私のような機能を呼び出してきたsin()し、sqrt()あまり考えず年間のを-なぜ必要がありますmath.erf()またはscipy.stats.norm.cdf()任意の異なること？ しかし、今、私は心配しています。私の質問は： 一般的に、ドキュメントで特別な言及がない場合、これらの種類の関数は、IEEE倍精度浮動小数点で提供される精度の範囲内で、小数点以下の最後まで完全に正確であることを意味しますか？ Python math.erf()やSciPy scipy.stats.norm.cdf()は特にそうですか？どうしてわかりますか？ このmanページはsin()言う… これらの関数は、引数がpiの倍数に近いか、0.0から離れていると、精度が低下する可能性があります。 サイン関数が周期的で対称であるのに、なぜこのような警告が存在するのでしょうか？最適な精度を得るには、入力を正規化するための呼び出し側に負担がかかるようです。 一方、MozillaのドキュメントでMath.sin()は、正確さや正確さについては何も述べられていません。それはそれが完全に正確であることを意味しますか、それともMath.sin()他の場所のように、JavaScriptの特定の状況でのみ正確であることは「共通の知識」ですか？

9 documentation  math  floating-point  numeric-precision 

Stack Overflowで答えを見つけてバグを解決することがよくあります。なぜ自分がしたことのスニペットを追加してから、Webから記事またはページへのリンクを追加することは悪い習慣ですか？

9 documentation 

私は、基本的なよく知られている文字列メトリックの実装を提供する小さなライブラリに取り組んでいます。主に私自身の教育のために。ですから、少し時間があるときに開発が行われます。 このため、私はほとんどのプロセスを自動化しているので、バージョンをリリースするのに、手間をかけずに頻繁に行うことができます。ただし、例が含まれているため、Java docの保守は依然として負担です。 APIが進化するにつれ、各例を手動で繰り返し確認する必要があります。これを行うより良い方法はありますか？ ドキュメントと例を別のプロジェクト（Caliperチュートリアルなど）に移動することを検討したので、通常のコードと一緒にリファクタリングしてコンパイルできます。ただし、これにより、ドキュメントが目的のクラスから移動します。 そうそう。ケーキも食べてみたいです。：D * <h2>Tokenization</h2> * * Tokenization cuts up a string into tokens e.g. * <code>chilperic ii son of childeric ii</code> is tokenized into * <code>[chilperic, ii, son, of, * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing * the individual tokens e.g. * …

9 java  documentation  javadocs 

休業。この質問には、より焦点を当てる必要があります。現在、回答を受け付けていません。 この質問を改善してみませんか？質問を更新して、この投稿を編集するだけで1つの問題に焦点を当てます。 4年前休業。 別のドキュメントとしてではなく、なぜソースコードの自然言語記述（つまり、コード行が記述された理由）をソースコード内に埋め込むのですか？ 現代の開発環境（高解像度モニター、デュアルモニターなど）に提供される広大な不動産を考えると、IDEは、ソースコードが視覚的に分離されているが本質的にリンクされているセミロックステップパネルを提供できます。対応するコメント。たとえば、開発者はハイパーリンクマークアップ言語（追加のソフトウェア要件へのリンク）でソースコードコメントを書くことができます。これにより、ドキュメントがソースコードを乱雑にするのを同時に防止できます。 このようなソフトウェア開発メカニズムを阻害する欠点は何ですか？ 質問を明確にするためのモックアップ： カーソルがソースコードの特定の行（上記の青色の背景で表示）にある場合、カーソルのある行に対応するドキュメントが強調表示されます（他の詳細と区別されます）。質問で述べたように、カーソルがソースコード内を移動するとき、ドキュメントはソースコードとロックステップのままです。ホットキーで「ドキュメントモード」と「開発モード」を切り替えることができます。 潜在的な利点は次のとおりです。 画面上のソースコードとドキュメントの同時表示 （言語に関係なく）ソースコードとは関係なくドキュメントを編集する機能 マージの競合なしに、ドキュメントとソースコードを並行して作成する 優れたテキスト形式のリアルタイムハイパーリンクドキュメント さまざまな自然言語への準リアルタイム機械翻訳 コードのすべての行は、タスク、ビジネス要件などに明確にリンクできます。 ドキュメントは、コードの各行が記述されたときに自動的にタイムスタンプを付けることができました（メトリック） アーキテクチャ図、関係を説明する画像などを動的に含める 単一ソースのドキュメント（ユーザーが手動で含めるためのタグコードスニペットなど）。 注意： ドキュメントウィンドウは折りたたむことができます ソースファイルを表示または比較するワークフローは影響を受けません 実装がどのように行われるかは詳細です。ドキュメントは次のようになります。 ソースファイルの末尾に保持されます。 規則（filename.c、filename.c.doc）で2つのファイルに分割します。または 完全にデータベース駆動 ハイパーリンクされたドキュメントとは、外部ソース（StackOverflowやWikipediaなど）および内部ドキュメント（つまり、ビジネス要件ドキュメントを相互参照できるサブドメイン上のWiki）およびその他のソースファイル（JavaDocsに類似）へのリンクを意味します。 関連スレッド：業界のドキュメントに対する嫌悪感とは何ですか？

9 development-process  documentation  source-code 

これは、回答のディスカッションとこの質問のコメントを参照しています。業界でのドキュメントへの嫌悪とは何ですか？。その答えは、「コードは嘘をつくことができない」ので、ドキュメントの代わりに頼りになる場所であるべきだと主張しました。いくつかのコメントは「コードは嘘をつくことができる」と指摘しました。少なくとも部分的にはドキュメントの扱いが不十分で不適切であるために、双方に真実があります。 嘘のコードを探して、既存のドキュメントと比較する必要がありますか？それともそれは通常それがしている必要があることのための最良の情報源ですか？それがアジャイルコードである場合、それは嘘をつく可能性が低くなりますか、それともそのコードはまったく嘘をつきませんか？

9 documentation 

プロジェクトを離れようとしています。行く前に、上司からコードの文書化を求められました（あまり文書化していません）。大したことではなく、プロジェクトはそれほど複雑ではありません。しかし、私は自分のドキュメンテーションの中で、「XYZの行でそのようなことが起こることに気づく」と言いたい場所を見つけています。 この場合、コードの1行を追加または削除するとすぐにドキュメントが古くなるため、特定の行番号を参照しても意味がありません。行番号で参照せずに特定のコード行を参照するためのベストプラクティスはありますか？ 私は次のようなコメントでコードを散らかすことを検討しました： /* linetag 38FECD4F */ ここで、「38FECD4F」はその特定の行の一意のタグです。次に、「 '38FECD4F'とタグ付けされた行で、そのようなことが起こることに注意してください」というドキュメントを挿入できます。 他のアイデアは？コードユニットの特定の部分よりも全体としてドキュメント化する方が一般的には良いと思いますが、この特定のプロジェクトの場合、手続き型コードの長い列があり、小さいユニットにリファクタリングされたことはありません。

9 documentation  comments 

他の人がこれをどのように行っているのか見てみたいです。特に、複数の異なるクライアントが、わずかに異なるビジネスルールで同じソフトウェアベースを使用している状況では。すべてがどのように機能するか、またはビジネスルールを文書化するために、どのような方法を使用していますか。 基本的には、新しい開発者がチームにやって来たときに、バグのないものと適切に機能させることには明らかに違いがあるため、チームがどのように機能するのかを簡単に確認できます。 何かを処理する方法について質問が出るたびにアーキテクトやBSAを会話に参加させる必要はなく、リソースを活用するほうがいいでしょう。

9 documentation  business-rules