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

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

236 programming-practices  documentation  comments 

私のチームメンバーの1人は、自分のコードでコメントを作成することを常に避けています。 彼のコードは自己文書化されておらず、他のプログラマーは彼のコードを理解するのに苦労しています。 私は彼に彼のコードをコメントするように何度も頼んだが、彼はただ言い訳をするか、または彼が後でそれをすることを主張する。彼の懸念は、コメントの追加に時間がかかりすぎてプロジェクトが遅れることです。 彼に彼のコードを適切に文書化するよう説得するために、どのような議論を彼に提示できますか？ そのメモでは、コードのコメントに焦点を当てるのは間違っていますか、これは対処すべき大きな問題を示していますか？

183 teamwork  team  comments 

私は、命に関わるソフトウェアを製造する店で働いており、コードを読みやすくして潜在的に命を救うことを意図したコメントルールに対処しました。私の経験では、この要件はチェックリストにチェックを入れるのは頭の痛い雑用になり、理解可能なコードを書くことに集中し続けるのに役立ちません。また、ピアレビューアが、コードを理解しやすくする方法について、より有意義な会話をすることを妨げます。 また、コメントのない学生コードを評価し、それらを無視するためにマークダウンする必要がある理由を確認しました。 適切な名前を使用し、構造をシンプルにし、機能を短くし、モジュールに焦点を当てると、コメントを最小限に抑えることができるほど十分にコードを理解しやすくなります。 また、コメントは、コードが方法ではなく、コードが実行する理由を説明する必要があることも理解しています。 このすべてを考えると、このアイデアをキャプチャする良いコーディング標準を書くことさえ可能ですか？ピアレビューに関連するものの、「42行目にコメントするのを忘れた」以上の有用なメモを生成する、気まぐれなチェックリストアクティビティにならないもの。 このルールがチェックリストの行として扱われる場合に必要となる種類のコードの例： /* Display an error message */ function display_error_message( $error_message ) { /* Display the error message */ echo $error_message; /* Exit the application */ exit(); } /* -------------------------------------------------------------------- */ /* Check if the configuration file does not exist, then display an error */ /* …

142 coding-standards  comments  standards  naming-standards  standardization 

私の同僚があると考えているすべてのイン・コードのコメント（つまり、いないのjavadocスタイルのメソッドやクラスのコメント）の使用があるコードのにおい。どう思いますか？

100 comments  anti-patterns 

ジュニア開発者はこちら。 私は現在、私の会社の大顧客向けのWebアプリケーションで単独で作業しています。先月始めました。クライアントは、各ソフトウェアプロジェクトに少なくとも25％のコメントを求めています。 私は以前のアプリケーションのコードをチェックしました、そして私の観察はここにあります： 各ファイルはコメントブロックで始まります（パッケージ、最終更新日、会社名、著作権） すべての変数は名前でコメント化されます // nameOfCustomer public String nameOfCustomer すべてのゲッターとセッターがコメントされます 非常に少数の有用なコメント 開発者は、品質や有用性に関係なく、25％のしきい値に達するためにできるだけ多くのコメントを配置するようです。私の会社は、「クライアントが望んでいるとおりにそれを行う」と言っています。 私はこれについてクライアントと直接話しませんでした。これまでの私の議論は次のとおりです。 読み書きする無駄な行（時間の無駄） コメントが時々更新されない（混乱の原因） 開発者が実際に役立つコメントを使用または信頼する可能性が低い このテーマに関するアドバイスは何ですか？状況をどのように処理すればよいですか？

96 project-management  comments  client-relations  hierarchy 

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

86 documentation  comments 

コメントに関して、新しい同僚と議論をしています。私たちはどちらもClean Codeが好きで、インラインコードのコメントを避け、クラスとメソッドの名前を使用してそれらの動作を表現する必要があるという事実にまったく問題ありません。 ただし、主に単一の責任原則パターンを維持しやすいように、クラスの目的と実際に何が表されているのかを説明しようとする小さなクラスの要約を追加するのが大好きです。また、メソッドが何をすべきかを説明する1行の要約をメソッドに追加することにも慣れています。典型的な例は簡単な方法です public Product GetById(int productId) {...} 私は次のメソッドの概要を追加しています /// <summary> /// Retrieves a product by its id, returns null if no product was found. /// </summary メソッドがnullを返すという事実は文書化されるべきだと思います。メソッドを呼び出したい開発者は、メソッドがnullを返すか例外をスローするかどうかを確認するためにコードを開く必要はありません。インターフェースの一部であることがあるため、開発者はどのコードが実行されているのかさえ知りませんか？ しかし、私の同僚は、これらの種類のコメントは「コード臭」であり、「コメントは常に失敗」であると考えています（Robert C. Martin）。 コメントを追加せずに、これらの種類の知識を表現および伝達する方法はありますか？私はロバートC.マーティンの大ファンなので、少し混乱しています。要約はコメントと同じであるため、常に失敗しますか？ これはインラインコメントについての質問ではありません。

83 comments  clean-code 

次のコードを書きました。 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 

Subversion（私たちが仕事で使用しているもの）は、コミットに関するコメントを要求するように設定できることを知っていますが、これを単純にオンにする力はありません。私はことを知っている私の唯一のメモリジョガーとして、急速にコミットの背後にある理由を理解するならば、それは、便利ですので、私のコミットをコメントした理由があります。ただし、これは私が常に受け取る2つの応答に対抗するには十分ではないようです。 時間がかかりすぎて、変更をレポに入れたいだけです。 差分を見るだけで十分です。 単にJIRA課題IDを入力することの価値と、それがどのように自動的に課題に結び付けられるかを示していますが、まだサイコロはありません。 最悪なのは、電話をかけることができる人が同じキャンプにいることです。気にする必要はなく、差分を見ることに問題ありません。 私はそれが正しいことだと知っていますが、どうすれば彼らに光を見せることができますか？仲間の開発者を納得させることができなくても、ビジネスのためにそれが正しいことだと経営者に納得させるにはどうすればよいですか？

78 version-control  comments 

私は上司に教えられています（学校を卒業したばかりで、彼は少しプログラミング経験のある人が欲しかったので、彼はその会社が専門とするものについて私に訓練することを選択しました）、ASP.NET MVCアプリケーション、いくつかのHTMLとCSSでの作業を開始しました。彼が私に提供してくれたWebデザインには問題ありません（明確にすることなく理解するのは非常に簡単です）。 しかし、たとえば、彼は私にASP.NET MVCに関連するタスクを提供してくれました。しかし、彼は私に与えたコードでは何も説明しません。（私たちはVisual Studio 2013でソース管理を使用しています）、文字通り何百行ものコードであり、何をすべきかについての背景はありません。私が見ている種類のコードは、今まで見たことのないコードなので、試してみて理解するのは本当に難しいです。 私は彼にさらに質問をしようとしますが、彼は常に仕事をしています（彼自身の仕事です）。 それで、物事を把握するまで私を助けてくれる何か、上司に彼に与えられたコードにコメントを入れるように頼むにはどうすればいいですか？

72 comments 

あなたがXXXコメントで見るとき、人々は一般に何を意味します。時折、次のようなコメントが表示されます。 # XXX - This widget really should frobulate the whatsit もちろん、コメントの意味はわかりますが、XXXは一般的にどういう意味ですか？「これはハックです」と言っているのでしょうか、それとも「おそらくこれを後で再検討する必要がある」でしょうか。それとも、まったく別のことを言っていますか？

72 comments  coding-standards 

私は自分が書いていた（古風なVisual Basic 6.0）コードで次のコメントを書いていることに気付いた。 If WindowState <> 1 Then 'The form's not minimized, so we can resize it safely '... End if コメントで「私たち」を無意識のうちに使用する理由がわかりません。誰かがコードをステップスルーするのを想像しているのではないかと思っています。まるでそれらが実際に発生するのを見るのではなく、実際に各行のすべてのコマンドを「行っている」かのようです。この考え方では、私はI can resize it現在、それを「やっている」ので、またはyou can resize it、「将来」それをやっている人と話しているかのように使用できますが、これらのケースの両方は私は自分のコードを他の人に導くかのように「私たち」を使用します。 私は単純にそれを書き換えてit can be resized問題を回避できますが、それは私の好奇心を引き起こしました：コメントでこのような最初の人を使用することは一般的ですか、それとも気が散るおよび/または専門家でないと考えられますか？

63 comments  coding-standards 

バックグラウンド 私は、ゼロダウンタイム展開の実装を検討しているチームで働いています。これを実現するために、ブルー/グリーン展開戦略の使用を計画しています。研究を行う上で私が理解していることの1つは、データベースの変更を行うことがどれほど複雑になるかです。カラムの名前を変更するなどの簡単な操作は、完了するまで3回の完全なリリースサイクルを必要とします。 変更の完全なロールアウトに複数のリリースサイクルがかかると、ヒューマンエラーが発生する可能性が大きくなるように思えます。リンクされた記事では、2つのリリースにはコードの変更が必要であり、3つのリリースにはデータベースの移行が必要であることを示しています。 私が探しているもの 現在、何かを行うことを覚えている場合は、問題管理システムでチケットを作成できます。または、TODOコメントを作成することもできますが、おそらく完全に忘れられます。 私が探しているのは、TODOコメントに期限があり、この期限が切れた場合、継続的インテグレーションシステム（現在使用する未定）がビルドを拒否する方法です。 たとえば、列の名前を変更する場合、最初の移行を作成し、次に2つのTODOコメントを作成して、残りの2つの移行が作成されるようにします。 // TODO by v55: Create migration to move constraints to new column, remove references to old column in app // TODO by v56: Create migration to drop old column これは実装するのはかなり簡単に思えますが、車輪の再発明をしたくないので、このようなものがすでに存在するかどうか疑問に思っています。 追加の考え ローリングデプロイメントとブルー/グリーンデプロイメントがベストプラクティスであると考えられるため、ここでXYの問題に苦しんでいるように感じます。データベースの更新の痛みを軽減するソリューションを見つけることができないのは奇妙に思えます。私が間違っていることを完全に調査していると思われる場合は、コメントでお知らせください！とはいえ、私が挙げたデータベースの例はほんの一例に過ぎず、期日付きのTODOコメントは他の状況でも役立つと思うので、この特定の状況に近づいていたとしても、私は本当に自分の答えにしたい実際の質問も。ありがとう！ 編集：これが役立つ別の状況を考えました。機能のトグルを使用して、準備ができたときにアプリの一部を有効にする場合、それらをクリーンアップするように注意する必要があります。そうしないと、Toggle Debtになる可能性があります。期限付きのコメントは、これを思い出す良い方法です。

51 continuous-integration  deployment  comments  continuous-delivery 

誰かがすべてのメソッドの前に/// <summary>コメントブロック（C＃）を付けるべきだと言ったことがありますが、その 理由は説明しませんでした。 私はそれらを使い始め、それらが私をかなり悩ませるので、ライブラリと静的メソッドを除いてそれらの使用を止めました。それらはかさばり、更新するのをいつも忘れています。 /// <summary>コードでコメントブロックを使用する正当な理由はありますか？ 私は通常//、常にコメントを使用します/// <summary>。それは、私が考えていたブロックだけです。

49 c#  comments