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

多くの人が「コメントは「なぜ」ではなく「なぜ」を説明すべきだ」と主張しています。他の人は「コードは自己文書化されるべきである」と言い、コメントは少ないはずです。ロバートC.マーティンは、（コメントは言い換えると）しばしば「コメントは不適切に書かれたコードに対して謝罪する」と主張しています。 私の質問は次のとおりです。 複雑なアルゴリズムや、複雑で複雑なコードを説明的なコメントで説明することの何が問題になっていますか？ この方法では、他の開発者（自分を含む）がアルゴリズム全体を1行ずつ読んでその動作を理解する代わりに、簡単な英語で書いたわかりやすい説明コメントを読むことができます。 英語は、人間が簡単に理解できるように「設計」されています。ただし、Java、Ruby、またはPerlは、人間の可読性とコンピューターの可読性のバランスを取るように設計されているため、テキストの人間の可読性が損なわれます。人間は、同じ意味のコードを理解するよりもはるかに速く英語を理解できます（操作が簡単でない限り）。 だから、部分的に人間が読めるプログラミング言語で書かれた複雑なコードを書いた後、フレンドリーで理解しやすい英語でコードの操作を説明する記述的で簡潔なコメントを追加してみませんか？ 「コードを理解するのは難しくない」、「機能を小さくする」、「わかりやすい名前を使用する」、「スパゲッティコードを書かない」と言う人もいます。 しかし、それだけでは十分ではないことはわかっています。これらは単なるガイドラインであり、重要かつ有用なものですが、一部のアルゴリズムが複雑であるという事実は変わりません。したがって、それらを行ごとに読むと理解するのは困難です。 複雑なアルゴリズムを一般的な操作についてのコメントの数行で説明するのは本当に悪いですか？複雑なコードをコメントで説明することの何が問題になっていますか？

236 programming-practices  documentation  comments 

私は、上司が読んでフォローできるようにしたい説明や解説を、1行ずつ（または必要に応じて、たとえば画像ごとなど）与えるように特に求められました。 彼はプログラマーではないので、彼はコードに従うことができないので、すべてを英語に翻訳したいと思っています。 これを行うように誰かに頼まれましたか？ すべてのソースコードについてコメントし、JSDocを使用して、すべての関数、変数などの完全なドキュメントを生成し、実装例と、コメント付きの完全に機能するデモを含めました。 プログラマでない人のためにコードにコメントするために私ができることは他にありますか？ これは合理的な要求ではありませんか？ 更新 最後に、私は彼が求めていたことをするのに時間の良い使い方ではなかった理由をなんとか説明することができました。彼は理にかなった男であり、私の仕事が何を含んでいるかを理解していませんでした。彼がこの投稿を見たとき、彼はそれが通常のリクエストではないことをすぐに理解したと思います。 他のプログラマーが従うのに適したドキュメント（JSDocおよびインラインコメント-技術的な問題に関する追加のメモ）と、上司が従うプログラムのメインロジックの非常に広範なフローチャート図を提供しました。 最終的に、すべての関係者は満足し、私たちは前進しました。

155 documentation 

RFC 2606標準では、ドキュメントの例として使用する目的で、ドメイン名example.org、example.netおよびexample.comが予約されています。 例として使用できる電話番号（国コードを含む）に相当するものは何ですか？たとえば、ユーザーに電話番号を入力するための形式の例を提供するためですか？ 最良の場合、それは関連する規格によって電話番号の例として指定されたダミー番号であり、実際の加入者に起因するものではありません。

112 documentation  standards  help-documentation 

私が比較的大規模なプロジェクトを開発しているとします。すでにすべてのクラスと関数をDoxygenで文書化しましたが、各ソースコードファイルに「プログラマーのメモ」を置くことを考えていました。 これの背後にある考え方は、特定のクラスがどのように機能するかを素人の用語で説明することです（ほとんどのコメントがそうする理由だけでなく）。言い換えれば、仲間のプログラマーにクラスがどのように機能するかについての別の見方を提供することです。 例えば： /* * PROGRAMMER'S NOTES: * * As stated in the documentation, the GamepadManager class * reads joystick joystick input using SDL and 'parses' SDL events to * Qt signals. * * Most of the code here is about goofing around the joystick mappings. * We want to …

104 documentation  large-scale-project 

最新バージョンからのサードパーティSDKのロールバックに関する会議で、開発者がコミット履歴で最新バージョンを使用すべきではないというフラグをすでに立てていることが確認されました。 一部の開発者は、これは悪い習慣であり、代わりにソースファイル（つまり// Don't upgrade SDK Version x.y.z, see ticket 1234）またはプロジェクトレベルのREADMEファイルのいずれかに記載する必要があると主張しました。他の人は、コミット履歴はプロジェクトのドキュメントの一部であるため、私たち全員がとにかくそれを読んでいるはずなので、そのような情報の許容できる場所であると主張しました。 重要な情報を他の開発者に伝えるためにコミット履歴を使用する必要がありますか、またはそのような情報をプロジェクトREADMEや関連するソースファイルのコメントなどの別の場所に複製する必要がありますか？

94 version-control  documentation 

私はかなり大きなプロジェクトに取り組んでおり、そのためにいくつかの翻訳を行うタスクを受け取りました。翻訳されていないラベルがたくさんあり、コードを掘り下げていたときに、この小さなコードを見つけました //TODO translations これは私がこれらのコメントの意味を自分自身（そして他の人？）に考えさせましたそれを維持するか、新しい機能を追加します。これTODOは長い間失われます。 このコメントを書くことは理にかなっていますか、それとも開発者の焦点に留まるホワイトボード/紙/何かに書かれるべきですか？

86 documentation  comments 

次のコードを書きました。 if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } ここにはコメントアウトされた行があります。しかし、私はそれが差が間にあるものを明らかにすることにより、コードが明確になり考えるifとelse。違いは、色の強調表示でさらに顕著です。 このようなコードをコメントアウトするのは良い考えでしょうか？

83 documentation  comments 

まず、この質問では、ソースコードのコメントが良いか悪いかという論争から離れたいと思います。なぜ、何を、どのようにあなたに伝えるコメントについて話すとき、人々が何を意味するのかをより明確に理解しようとしています。 多くの場合、「コメントは理由を説明する必要があり、コード自体は方法を説明する必要があります」などのガイドラインがあります。抽象レベルで声明に同意するのは簡単です。しかし、人々は通常これを教義のように落とし、それ以上説明することなく部屋を出ます。私はこれが非常に多くの異なる場所や文脈で使用されているのを見て、人々がキャッチフレーズに同意できるように見えますが、彼らは完全に異なることについて話しているようです。 それでは、質問に戻ってください：もしコメントがあなたになぜ言うべきなら、私たちが話しているこの理由は何ですか？これが、そのコードがそもそも存在する理由ですか？これは、そのピースのコードがやるべきことですか？誰かが明確な説明をして、良い例を追加できれば本当にありがたいです（悪い例は実際には必要ありませんが、対比のために自由に追加してください）。 コメントが良いか悪いかについては多くの質問がありますが、なぜあなたに伝えるコメントの良い例が何であるかの特定の質問に対処する人はいません。

78 documentation  comments 

私は3か月前にプロジェクトに取り組んでいましたが、突然別の緊急プロジェクトが現れ、注意を向けるように頼まれました。 明日から、古いプロジェクトに戻ります。私は自分が何をしていたかを正確に覚えていないことに気付きます。どこから始めればいいのかわかりません。 振り返るときはいつでも、離れた場所から数分以内にプロジェクトを文書化できます。ベストプラクティスはありますか？

72 project-management  documentation 

平凡な共有ホスティングで、エンタープライズBlubフレームワークとBlubレベルのWebサーバーを備えたBlubの使用に縛られているため、現在の仕事を辞めるつもりです。私の同僚は友好的であり、私の上司は平均的な中小企業のオーナーです。技術的な理由から完全に辞めたいです。Blubに浸ることは私の脳に悪いことであり、私をより悪いプログラマーにしています。 私が去るとき、どうやってこれを上司や同僚に説明できますか？Blubに関する苦情を生産的に表現するにはどうすればよいですか？文書の後継者にどのような警告を残すことができますか？ （私が基準を満たしていることを確認しようとしています）

66 career-development  documentation 

よく文書化されたコードの重要性を理解しています。しかし、自己文書化コードの重要性も理解しています。特定の機能を視覚的に読みやすくするほど、ソフトウェアのメンテナンス中にすばやく移動できます。 とはいえ、私は大きな機能を他の小さな機能に分離するのが好きです。しかし、1つのパブリックメソッドを提供するためだけに、クラスが5つまで持つことができるようになります。ここで、5つのプライベートメソッドに5つのパブリックメソッドを掛けると、それらのパブリックメソッドによって1回だけ呼び出される可能性のある、25の隠しメソッドを取得できます。 確かに、これらのパブリックメソッドは読みやすくなりましたが、機能が多すぎるのは悪い習慣だと思わざるを得ません。 [編集] 人々は、なぜ機能が多すぎるのが悪い習慣だと思うのかと私に尋ねてきました。 簡単な答え：それは直感です。 私の信念は、少しの間、ソフトウェアエンジニアリングの経験に支えられていません。「ライターのブロック」を与えたのは、プログラマーにとってだけの不確実性です。 過去には、私は個人的なプロジェクトのみをプログラミングしてきました。チームベースのプロジェクトに移ったのはつい最近のことです。ここで、他の人がコードを読んで理解できるようにします。 何が読みやすさを改善するのか分かりませんでした。一方では、1つの大きな関数を、わかりやすい名前を持つ他の小さな関数に分離することを考えていました。しかし、それは単に冗長であると言っている私の側面がありました。 それで、正しい道を選ぶために自分自身を啓発するように私はこれを求めています。 [編集] 以下は、私がどのように2つのバージョンが含ま可能性が私の問題を解決します。最初のものは、コードの大きな塊を分離しないことでそれを解決します。2番目は別のことを行います。 最初のバージョン： public static int Main() { // Displays the menu. Console.WriteLine("Pick your option"); Console.Writeline("[1] Input and display a polynomial"); Console.WriteLine("[2] Add two polynomials"); Console.WriteLine("[3] Subtract two polynomials"); Console.WriteLine("[4] Differentiate two polynomials"); Console.WriteLine("[0] Quit"); } 2番目のバージョン： public static int …

63 programming-practices  code-quality  documentation 

自動ドキュメント生成はさまざまなツールで実行できますが、GhostDocはその中でも最も優れたツールの1つです。ただし、定義上、生成されるものはすべて冗長です。それは方法など、クラス、および出力の英語の名前を見てとるかもしれないより冗長にそれらを説明します。最良の場合、読者が頭の中ですでにできることを行います（ここからの例）： /// <summary> /// Initializes a new instance of the <see cref="Person"/> class. /// </summary> public Person() ... 最悪の場合、名前の意味をヒューリスティックに把握しようとする試みで実際に誤解を招く奇妙なドキュメントを生成することになります。 /// <summary> /// Riches the text selection changed. /// </summary> /// <param name="richTextBox">The rich text box.</param> private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ... GhostDocに対する態度は「何らかの形式的なXMLドキュメントを持っている方が本質的に良い」と思われますが、そのドキュメントが100％冗長なのはなぜですか？せいぜい大量のスペースを無駄にしているだけではありませんか？ 私の職場では、すべてを文書化する必要があり、ほとんどの場合、GhostDocの自動生成ドキュメントを使用します。あなたはこれを行いますか？実際にドキュメントを自分で書くつもりがない場合は、単にコードをドキュメント化しないままにしておかない合理的な理由はありますか？

60 documentation  automation  automatic-programming 

よく説明しようとしているサードパーティのプログラムを含むユーザードキュメント（SOP）を書いています。そのようなプログラムの1つは、初期化/起動ルーチン中に表示されるグラフィック以外に、起動の表示をほとんど提供しないサーバーです。 開発者として、このウィンドウをクイックステータスインジケーターとして使用し、これを聴衆（オペレーター/エンジニア）に伝えたいと思いますが、それが何と呼ばれるかわかりません。私の最初の質問は、起動時に表示されるグラフィックに正式な名前または広く受け入れられている名前があるかどうかです（以下の例）。第二に、観客にアイデアを素早く（そしてグラフィックなしで）伝えるこれを参照する好ましい方法は何ですか？ 例 |

59 documentation  component  jargon 

時々、私が書いているコードの一部が、その名前が基本的にコメントとして繰り返されることを自明である（またはそうであるように思われる）状況に自分自身を見つけます： class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; }; } （C＃の例ですが、質問は言語に依存しないようにしてください）。 そのようなコメントは無意味です。私は何を間違えていますか？間違っているのは名前の選択ですか？このような部分をより良くコメントするにはどうすればよいですか？このようなことに対するコメントをスキップする必要がありますか？

54 programming-practices  documentation  language-agnostic 

jsdocsのようなツールを使用すると、コード内のコメントに基づいてコードベースに静的なHTMLファイルとそのスタイルが生成されます。 これらのファイルをGitリポジトリにチェックインするか、.gitignoreで無視する必要がありますか？

49 git  documentation