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

一部の言語のドキュメントで「ある」ではなく「と同等」と表示されるのはなぜですか？ たとえば、Python Docsは言う itertools.chain(*iterables) ... 以下と同等： def chain(*iterables): # chain('ABC', 'DEF') --> A B C D E F for it in iterables: for element in it: yield element あるいは、このC ++の参照にfind_if： この関数テンプレートの動作は次と同等です： template<class InputIterator, class UnaryPredicate> InputIterator find_if (InputIterator first, InputIterator last, UnaryPredicate pred) { while (first!=last) { if (pred(*first)) return …

23 c++  python  documentation  compiler 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 去年閉鎖されました。 数か月後にコードの読み取りと閲覧を最小限に抑えるようにコードを文書化したい。 さまざまな種類のドキュメントがあることを知っています（ソースコードと外部、シーケンス図など）。 コードを効率的に文書化する方法を知りたいので、数か月後にコードを確認したいとき、コードの読み取りとコードフローの理解に費やす時間が少なくなります。

22 documentation  code-reviews  documentation-generation  help-documentation 

フィールドのgetterとsetterの「JavaBeanの」構文を含む文書すべてに論争の対象のビットようだ：人々は言うその不必要に長いと繰り返し破断DRY（自分を繰り返さない）、命名規則を説明しなければならないことのすべてを、また、コード/ドキュメントが乱雑になります。時にはそれらの引数が機能します。しかし、他の場合には、これで終わります： 上記は、これらの原則に大胆に従っているオープンソースプロジェクトに共通しています。完全に役に立たないドキュメントが残っています。それは、下で何が起こっているのか、考えられる効果、または期待値が何であるのかについては何も説明していません（nullになるか、nullにならないのかわかりません。Javadocは教えてくれません）。 それでは、いつ文書化する必要がありますか？ときどきコードが乱雑になっても、すべてを文書化しますか？それとも、私の目には「明らか」だから何も文書化しませんか？

22 documentation 

「ユニットテストは、テスト中のコードのドキュメントの非常に重要なソースである」という流れの中でステートメントを読んだ回数を数えられません。それらが真実であることを否定しません。 しかし、個人的には、ドキュメントとしてそれらを使用していることを発見したことはありません。私が使用する典型的なフレームワークの場合、メソッド宣言はそれらの動作を文書化しており、それが私が必要とするすべてです。そして、ユニットテストでは、そのドキュメントに記載されているすべての内容に加えて、内部的なものがバックアップされる可能性があるため、一方では文書化を複製し、他方では無関係なものを追加する可能性があります。 質問は次のとおりです。ユニットテストはいつドキュメントとして使用されますか？コメントがすべてを網羅していないときは？開発者はソースを拡張しますか？そして、ドキュメント自体が公開できない有用で関連性のあるものを公開しますか？

22 unit-testing  documentation 

現在、機能および技術仕様を2列形式で作成しています。要約文と技術的詳細。詳細は、多くの場合、図、レイアウト設計などの付録を参照しています。 しかし、私はそれをどのように書くのに苦労しています： 過去の時制のように、作業が完了したかのように、既存の作業のハイライト拡張を示すのに苦労します。Xを行う必要があるため、将来の時制は、やることリストまたはTenseニュートラルのように聞こえます。 さらに混乱を加えるために、この仕様は、第一言語として英語を持っていない人々によって読まれるかもしれません。

21 documentation  specifications  writing 

背景： 私の共同研究者と私は学術雑誌の記事を書いています。研究の過程で、Javaでシミュレーションプログラムを作成しました。シミュレーションプログラムを他の人が自由に利用できるようにしたいと考えています。GitHubリポジトリでコードをホストすることにしました。他の人が簡単に使用できるようにするために、次のような優れたドキュメントを作成します。 各クラスとメソッドのJavadoc コードの使用方法 コードの高レベルの構造を記述する 私の高レベルの質問は次のとおり です。プログラムの高レベルの構造を説明するために使用できる単語と図の良い例を提供できますか？ これにはサブ質問として含まれます： どのパッケージにどのクラスが含まれているかをどのように示しますか？ 他のパッケージに依存するパッケージをどのように表示しますか？ プログラム内のオブジェクト/クラスがどのように連携するかをどのように示しますか？ 私たちは、コードの設計にドメイン駆動設計原則を使用しようとしました。ドメイン内のオブジェクトと、これらのオブジェクトをエンコードする特定のソースコードファイルとの対応をどのように示しますか？（以下のプロジェクトの私の「ユビキタス言語」の説明を参照してください。） これまでにやったこと ユビキタス言語 コードの「ユビキタス言語」の説明をファイルのubiquitous-language.md次の内容に入れます。 このプロジェクトの目的は、異なるリードタイムモデル、レポート遅延、および需要モデルの下で、単一施設を備えた単純なサプライチェーンで補充ポリシーがどの程度うまく機能するかを調査することです。 各期間で、次のイベントが発生します。 出荷が現在の期間に施設に到着するようにスケジュールされている場合、施設の在庫レベルはX単位だけ増加します。 現在の期間がレポート期間であることがスケジュールに示されている場合、施設はレポートをサプライヤーに提出し ます。サプライヤーは、受信することができるレポート によって指定されるように、数週間の遅れまたは、瞬時スケジュール。 サプライヤがレポートを受信した場合、補充ポリシーに基づいて、 Xユニットの補充量を計算します。出荷製品のXユニットは、L期間のリードタイムの後に到着する予定であろう。 顧客は施設に到着し、製品のXユニットを要求します。満たされていない需要は失われます。 ソースコード構造 コードの不完全な「高レベル」説明をファイルstructure.mdに入れます。内容は以下のとおりです。 パッケージレベルの構造 最高レベルでは、ソースコードは3つのパッケージに編成されています。 com.gly.sfsmainメソッドを 持つメインクラスはこのパッケージにあります。 com.gly.sfs.model ドメインモデルクラスはこのパッケージにあります。 com.gly.sfs.util ヘルパークラスはこのパッケージにあります。

20 java  documentation 

だから私たちはそのようなインターフェイスを持っています /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos /// </summary> void Create(Foo foo); /// <summary> /// Does Bar stuff /// </summary> void Bar(); } 最近、私たちは、上記のようなXML文書がたくさんあることを生成し、確認することを含む文書の話をしました。しかし、これはドキュメントの多くの重複を引き起こしました。実装例： /// <summary> /// A Foo Creator which is fast /// </summary> …

20 c#  documentation  xml  documentation-generation 

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 6年前に閉鎖されました。 WordPressとBuddyPressを使って私のためにソーシャルネットワークプロジェクトに1年以上費やした後、私のプログラマーは、週ごとに報酬を受け取っていたにもかかわらず、全期間にわたって姿を消しました。はい、私はメールトラッカーを使用して確認し、私のメールを開いているのを確認したので、彼は死んでいませんが、彼は応答しません。彼は別の仕事を得たようです。なぜ彼はそう言うことができなかったのだろうか。そして、私は彼がやったことのない仕事のために彼に事前給料を支払った。 問題は、彼がコーディングしたほとんどの関数の完全なドキュメントを求めたことがないことです。そして、この1年以上の期間には多くの関数があり、それらのいくつかにはまだ修正しなかったバグがあります。今ではすべて混乱しているようです。 最初にすべきことは何ですか？どうすればいいですか？ 最初にやるべきことは別のプログラマーを獲得することだと思いますが、プログラマーが問題なくすべての機能に取り組むことができるように、現在のすべてのコードを文書化することから始めましょう。 それが最初にすべきことですか？はいの場合、どうすればいいですか？ このようなものに必要な標準的なドキュメントは何ですか？すべてのコードのドキュメントを作成してバグを修正するだけのプログラマを入手できますか、それともドキュメントは本当に重要ではありませんか？ また、別の「個人」プログラマーを取得する方が良いと思いますか、それとも私のプロジェクトに割り当てられたプログラマーが消えた場合、別のプログラマーが彼の代わりになりますように、彼らのために働くプログラマーを持っている会社を取得しますか？これが最初に取るべきアプローチだと思います。

19 documentation  hiring  outsourcing  knowledge-transfer  wordpress 

まれですが、コードに数学ロジックを含める必要があります。使用される概念はほとんど非常に単純ですが、結果のコードはそうではありません-不明な目的を持つ多くの変数、およびそれほど明白ではない意図のある操作。コードが判読不能または保守不能であることを意味するのではなく、実際の数学の問題よりも理解が難しいというだけです。私は理解が最も難しい部分にコメントを付けようとしますが、それらをコーディングするのと同じ問題があります- テキストには数学の表現力がありません。 複雑なコードの一部、できればコード自体の背後にあるロジックを説明する、より効率的で理解しやすい方法を探しています。私はTeXを検討しました-ドキュメントを書き、コードとは別に生成します。しかし、それから私はTeXを学ぶ必要があり、ドキュメントはコード自体にはありません。私が考えたもう1つのことは、紙/ホワイトボードに書かれた数学表記、方程式、図の写真を撮り、それをjavadocに含めることです。 より簡単で明確な方法はありますか？ PS 変数に（のtimeOfFirstEvent代わりにt1）わかりやすい名前を付けると、実際にはコードがより冗長になり、読みにくくなります。

19 java  documentation  math 

最近、私が現在扱っているコードベースの部分のリファクタリングに取り組んでいます-自分自身をよりよく理解するためだけでなく、コードに取り組んでいる他の人にとってそれをより簡単にするために。 私は、自己文書化コードは素晴らしいと考える側に傾く傾向があります。私はちょうどそれがきれいだと思うし、コードがそれ自体のために話すなら、まあ... それは素晴らしいです。 一方、javadocsなどのドキュメントがあります。私もこれが好きですが、ここのコメントが時代遅れになるという特定のリスクがあります（もちろん一般的なコメントも同様です）。ただし、それらが最新の場合、複雑なアルゴリズムを理解するなど、非常に役立ちます。 これのベストプラクティスは何ですか？自己文書化コードとjavadocsの間のどこに線を引きますか？

18 java  documentation  refactoring  javadocs 

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 5年前に閉鎖されました。 よく文書化されたソフトウェア開発が成功につながることは誰もが知っています。ただし、通常は、プレーンテキストだけでなくバイナリコンテンツもUML図などのドキュメントに含まれることを意味します。そして、私は多くの人がそれを言うのを聞いたことがあります。バージョン管理システムは、バイナリファイルの適切な場所ではありません。私はこの問題を完全に理解し、同意します。文書を保管するのに最適な場所はどこにあるべきか、何人かのベテランの開発者に尋ねました。Wikiは良いですが、別の潜在的な問題を検討しました。バージョン管理システムに保存されているソースコードは、Wikiの関連ドキュメントにどのように接続できますか？誰かがgitまたはmercurialのリポジトリを複製したとしましょう。彼/彼女はどのようにしてドキュメントを簡単に見つけることができますか？または、私は何かを見逃しましたか？ 一部のウィキシステムには、ソース管理システムと統合する機能があることを知っています。しかし、私の懸念は統合の能力に関するものではありません。gitリポジトリからソースコードのクローンを作成し、しばらくしてから電車に乗って、電車でオフラインで仕事を続けたい場合（これはDVCSの大きな機能です）。次に、電車でオフラインで作業しているため、ドキュメントにアクセスできないことに突然気付きます。一方、ドキュメントがgitリポジトリに保存されている場合、リポジトリが複製されたドキュメントにアクセスできます。

18 documentation  wiki 

あなたが仕事を辞める唯一の開発者であると仮定します。コード自体以外のどのような情報/素材を作成し、置き換えのために残す必要がありますか？ 明らかな答えは確かに「新しい仕事に望むものは何でも」ですが、私が新しい仕事を始めてからしばらく経ち、私が必要としていた最も重要なことは当時忘れていました。 考えています： アカウント/パスワード 機器、バックアップ、ソフトウェアCDの場所 ほかに何か？

18 documentation  knowledge-transfer 

私のチームの開発者の1人は、メソッドの署名のEVERYパラメーターにjavadocコメントを書く必要があると考えています。私はこれが必要だとは思わないし、実際、それは有害でさえあると思う。 まず、パラメーター名は説明的で自己文書化されるべきだと思います。パラメータの目的がすぐに分からない場合は、おそらく間違っています。ただし、パラメータの目的が不明な場合があることは理解しています。そのため、その場合は、パラメータを説明するjavadocコメントを作成する必要があります。 しかし、すべてのパラメーターに対してこれを行う必要はないと思います。パラメータの目的がすでに明らかな場合、javadocコメントは冗長です。あなた自身のために余分な仕事を作成しているだけです。さらに、コードを保守する必要がある人のために余分な作業を作成しています。メソッドは時間とともに変化し、コメントを維持することはコードを維持することとほぼ同じくらい重要です。「XはYをZの理由で行う」などのコメントを何回見て、そのコメントが古いことを確認しましたが、実際にはメソッドはXパラメーターさえも取りません。人々はコメントを更新するのを忘れているので、それは常に起こります。誤解を招くコメントは、まったくコメントしないよりも有害であると主張します。したがって、過剰なコメントの危険性があります。不要なドキュメントを作成することにより、 しかし、私は自分のチームの他の開発者を尊重し、おそらく彼が正しいと私は間違っていることを受け入れます。だからこそ、仲間の開発者に質問を投げかけます。実際、すべてのパラメーターにjavadocコメントを書く必要がありますか？ここでは、コードは会社の内部にあり、外部の第三者によって消費されることはないと想定しています。

17 java  documentation  source-code  comments  maintainability 

私はソフトウェアプロジェクトをより正式に文書化する方法を検討しており、IEEE 830-1998：ソフトウェア要件仕様の推奨プラクティスについて学びました。ただし、そのリンクからわかるように、このリンクは置き換えられています。 私は、830-1998、そしておそらく830-1993でさえ、おそらく使用に問題がないことを知っています。ただし、他に何もなければ、どの標準がそれに取って代わったかを知りたいと思います。この場合、それは問題ではないかもしれませんが、他の標準がより技術的なものに取って代わられる場合、どこの標準が別のものに取って代わるかをリンクすることは良い考えだと思います（同じ行に別の標準がない場合（830、場合））。 それに言及する価値があります： IEEE Standards AssociationのWebサイトで「Software Requirements Specifications」または「Software Requirements」を検索する際の最新の標準は830-1993です。 SWEBOKの2004（現在）バージョンは830-1993（段落2.5）を参照しています。 このドキュメントのウィキペディアの記事には、この標準が置き換えられたという記述はありません。 TLDR：どの規格が他の規格に取って代わり、どの規格が830-1998に取って代わりましたか。

17 documentation  requirements  standards 

次のような「最小限のシステム要件」で出荷されるソフトウェアの例は数多く見られます。 Windows XP / Vista / 7 1GB RAM 200 MBストレージ これらは一般的にどのように決定されますか？明らかに特定の制約がある場合があります（プログラムがディスク上で200 MBを使用する場合、それは厳しい要件です）。これらの状況とは別に、RAMやプロセッサなどの場合は、多くの場合、ハードな制約なしで、より高速で高速であることがわかります。これらはどのように決定されますか？開発者は、合理的と思われる数字を作成するだけですか QAは、許容可能なパフォーマンスを備えた最も低い設定を見つけるまで、さまざまな要件をテストする厳密なプロセスを実行しますか？私の本能は、後者でなければならないが、実際にはしばしば前者であると言います。

17 documentation  requirements  qa