あなたのHTMLとCSSのコメントはどれくらい良いですか？

基本的なHTMLまたはCSSについて学習し始めるときに通常学習することの1つは、コードにコメントを書く方法です。ただし、多くのWeb開発者は、まだ有利にコメントを使用していません。 HTMLとCSSで広くコメントを使用する場合がありますが、適切に書かれた場合、意図的にワークフローを改善できます。

新しい会社での作業を開始すると、マニュアルやドキュメントの多くのページを見ると気が遠くなる可能性があります。すべての企業は異なります。つまり、コードベース、レガシーコードの量、フレームワークの開発、モジュラーコードの量は異なる場合があります。

「良いコードはコメントを必要としない」と言われていますが、コメントの

の欠如のために、自分が輪になって完全に紛失し、ドキュメントを探していることに気づいたことがありますか？ キーテイクアウト

HTMLとCSSでのコメントは、理解を促進し、一貫性を維持するだけでなく、開発プロセスを高速化し、効率的なコラボレーションを支援します。複数の開発者が同じプロジェクトに取り組んでいるチーム設定で特に役立ちます。

コメントは有益ですが、無理を避けてください。コードのすべてのブロックにコメントするのは、冗長で時間がかかる場合があります。コメントは簡潔で、コードが完全に明確でない場合にのみ使用する必要があります。 コメントは、擬似要素の目的、ネストされたコードブロック、なぜ重要なのか、またはコードブロックが削除されるのではなくコメントされた理由を説明するために使用できます。

メッセージメッセージやプル要求など、その他の形式のドキュメントも、開発プロセスの一部と見なされる必要があります。彼らはコンテキストと明確さを提供し、コラボレーションとコードレビューをより効率的にします。
コードコメントに関する2つの事実
• コメントはブラウザによって無視されます。
• コメントは縮小中に剥奪されます。

これらの2つの事実に基づいて、コメントは実際には機械用のものではないことを知っています。それらは、人間が読むことを意味しています。

コメントコードが重要である理由

コメントは一貫性を維持するのに役立ちます。あなたが構築しているものについて一貫した、よく書かれたコメントがある場合、あなたは毎回同じように物事を構築する可能性が高くなります。

コメントは理解を促進します。これは、1人がすべての仕事をしないことがあるチームでは本当に重要です。コメントを書くためにコメントを書くことができます。ロジックを理解するのに役立ちます。プロジェクトの終わりまでにすべてのコメントを維持しているわけではありませんが、ソリューションにどのようになったかをよりよく理解するのに役立ちます。それはあなたが後でより簡単にそのソリューションを改善するのに役立ちます。

コメントは、ホットフィックスやクイック修正を支援することもできます。コメントは実際にここで3つの方法で役立ちます。彼らは、開発者が迅速な修正を必要とする場合（特に支援しているフロントエンドチーム以外の開発者）、これらの修正が必要な場所をマークすることで役立ち、迅速な修正がどこに表示されるかを示すことができます。適用されており、ある時点で削除する必要があります。

コメントは、開発プロセスをスピードアップするのに役立ちます。関連するコメントを含めると、何を作成しているか、変更、または削除しているものをより明確に理解できます。

コメントにより、より効率的なコラボレーションが促進されます。プロジェクトまたはコードベースの内外がわかっている場合、ビットとピースをより速く実行する可能性が高く、したがってワークフローが改善されます。

コメントは多くの人を助けます。彼らは自分自身を助けるだけでなく、あなたのチームの他の人々を助けることができます。人々のソースコードで私のコードを盗まないようなコメントを見た時代は終わりました。私たちはかつて私たちのコードを非常に保護していましたが、「秘密」を共有したくありませんでしたが、今では人々がコードを共有し、プロジェクトに取り組み、協力する世界に住んでいます。 Webプロジェクトに関しては、ハリー・ロバーツ、クリス・コイヤー、ジョナサン・スヌークなどを称賛することを恥じていません。このコラボレーションの変化により、コメントの慣行にも注意し、仲間を支援する必要があります。

コメントに関しては避けるべきことがいくつかあります
絶対にすべてをコメントしないでください
コードのすべてのブロックにコメントする習慣に陥るのは魅力的かもしれませんが、これは有用または役立つよりも冗長性があります。コメントは、何かが完全に明確ではない場合にのみ行う必要があります。クラスに名前を付けるときにセマンティクスを検討した場合、コードはすでに理解しやすい場合があります。

これは、「良いコードにコメントを必要としない」という概念が生まれた場所でもあります。コメントは完全に避けるべきではありませんが、必要に応じてのみ使用されます。

あまりにも冗長にならないでください
私は物事を説明し、文書化するのが大好きなので、私のCSSにかなり長いコメントを書くことに個人的に罪を犯しています。ただし、小説を書くべきではありません。長いコメントは、書くことができるのと同じくらい読むのが苦痛です。あなたが簡潔になることができるなら、そうしてください。時々、CSSクラスに名前を付けるとき、次のアドバイスが与えられます。
クラス名をできるだけ短いが、必要に応じて作成します。

コメントにも同じことが当てはまります。自分で理解していることを確認するために、書いたコメントについて読むのは良いことです。あなたがコードに慣れていない人であり、あなたはコメントをガイドとして読んでいると想像してください。

コメントを書くのにあまり時間を費やさないでください

私はかつて私が取り組んでいたプロジェクトでファイルを見ました。

<span>// Update this with how many hours you have spent on this file:
</span><span>// TIME_WASTED = 438;</span>

コメントを書くのに多くの時間を費やす必要はありません。通常、いくつかの単語で十分です。コードをコメントしようとして、他の人がそれを理解することを確認するためにコメントをしようとして時間がかかりすぎている場合は、コードの一部が実際にリファクタリングが必要になる可能性があることを考慮してください。

コメントを使用するタイミングの例

擬似要素の目的を説明する

この例は、コンテンツ値が入力された擬似要素を示しています。

特にコンテンツとしてコンテンツとして表示されている場合、

擬似要素が何のためのものかはすぐには明らかではないかもしれません。コードブロックの上に短いコメントを使用すると、これを改善できます。

ネストされたコードブロックを説明するために

<span><span>.post__comment-container::after</span> {
</span>  <span>background-color: #f9f9f9;
</span>  <span>border: 1px solid #dedede;
</span>  <span>border-radius: 0.25em;
</span>  <span>color: #888;
</span>  <span>content: 'Post author';
</span>  <span>display: inline-block;
</span>  <span>font-size: 0.7rem;
</span>  <span>margin-left: 0.5rem;
</span>  <span>padding: 0.2rem 0.45rem;
</span>  <span>vertical-align: middle;
</span><span>}</span>

セマンティッククラスを可能な限り使用することは間違いなく役立ちますが、プリプロセッサを使用するときにCSSのブロックがネストされる理由は必ずしも明確ではないかもしれません。

/* Post author label for comment */

<span><span>.post__comment-container::after</span> {
</span>  <span>background-color: #f9f9f9;
</span>  <span>border: 1px solid #dedede;
</span>  <span>border-radius: 0.25em;
</span>  <span>color: #888;
</span>  <span>content: 'Post author';
</span>  <span>display: inline-block;
</span>  <span>font-size: 0.7rem;
</span>  <span>margin-left: 0.5rem;
</span>  <span>padding: 0.2rem 0.45rem;
</span>  <span>vertical-align: middle;
</span><span>}</span>

コメントがこのコードブロックが何をするかをコメントするには6つの単語で十分であり、誰かがドキュメントをスキムして停止またはスキップできるようになります。

理由を説明するために！

私たちはよく見ています！
綿密な検査で、フレームワークのデフォルト動作を無効にしています。

<span><span>.c-segment-controls.is-active</span> {
</span>  <span><span>.c-segment-controls__panel</span> {
</span>    <span>background-color: #fafafa;
</span>    <span>border: 1px solid #aaa;
</span>    <span>opacity: 1;
</span>    <span>transition: opacity 0.5s ease;
</span>  <span>}
</span><span>}</span>

コードブロックが単に削除されるのではなく、コメントアウトされた理由を説明する

<span><span>.c-segment-controls.is-active</span> {
</span>
  <span>/* Active state for segment controls panel */
</span>
  <span><span>.c-segment-controls__panel</span> {
</span>    <span>background-color: #fafafa;
</span>    <span>border: 1px solid #aaa;
</span>    <span>opacity: 1;
</span>    <span>transition: opacity 0.5s ease;
</span>  <span>}
</span><span>}</span>

下のコードブロックを見ると、これが問題ないと仮定するかもしれません。確かにそれはどこにも使用されていませんか？削除すると、後で必要なときにとにかくバージョンコントロールになりますよね？

しかし、それを削除すると、誰かがそもそもそれが存在することさえ知らないかもしれません。これをここに残すのは良い考えかもしれません：

<span><span>.c-accordion-container.ng-hide</span> {
</span>  <span>display: block !important;
</span><span>}</span>

他の種類のドキュメント

/**
 * Overriding some rogue Angular code.
 * Forces `display: block` so that the element can be animated.
 */

<span><span>.c-accordion-container.ng-hide</span> {
</span>  <span>display: block !important;
</span><span>}</span>

ドキュメントは非常に重要であり、コードのコメントだけではありません。タスクが完了したら、ピアレビューを受ける可能性があります。

メッセージ

をコミットします

バージョンコントロール（たとえば、git）を使用する場合、コードで有用なコメントを書くことについて知っていることを取ることができ、これをコミットメッセージに適用できます。

<span>// .c-segmented-button__icon {
</span><span>//   transform: translateY(calc((40px - 100%)/2));
</span><span>// }</span>

悪いコミットメッセージは、多くのコンテキストを与えません。彼らはずさんに見え、理解するのが難しい場合があります。リリースノートには役に立ちません。開発者が何が変わったかを知るのは難しいかもしれません。悪いコミットメッセージはしばしばこのように見えます。

/**
 * Calculation for vertical alignment.
 * Can be used when IE11 support is dropped.
 */

<span>// .c-segmented-button__icon {
</span><span>//   transform: translateY(calc((40px - 100%)/2));
</span><span>// }</span>

より良い例は、動詞を使用して、コミットで完了したタスクを説明します。さまざまなマイナーなタスクが異なるコミットに広がっています。

<span>// Update this with how many hours you have spent on this file:
</span><span>// TIME_WASTED = 438;</span>

カルマには、より良いコミットを書くための非常に簡単なガイドがありますが、クリスビームには非常に詳細なガイドがあります。 David Demareeは、「The Art of the Commit」というタイトルの記事を書きました。メッセージをコミットすることは間違いなくある程度の注意に値します。

リクエストをプル

一握りのコミットを書いた後、あなたは通常、仲間の1人が見るためのプルリクエストを作成します。詳細がほとんどないか、まったく説明のないプルリクエストが多すぎるのを見てきました：



プルリクエストを書いている場合、通常、誰かがあなたのコードを確認することを期待しています。その人を支援し、プロセスを容易にするには、プルリクエストに含まれるものの説明を書く必要があります。これは私のメンタルチェックリストです：

• チケット番号、タスク番号、または発行番号
• いくつかの言葉でタスクを言及します
• どのタイプのファイルを変更したかについて
に言及します
• それがバグの場合、変更の前後のバグがどのようなものであったかについて
• 変更後の予想される動作について説明します（同じである必要がありますか？）
• ブラウザ内またはコードのいずれかの変更を確認するために実行する必要がある手順をリストします
• 無視すべきものはすべて、たとえば別のブランチで扱われているバグ
必要に応じて、インターフェイスのスクリーンショットを含めます
この例は比較的単純であり、必要でない場合は上記のリストにすべてを含める必要はありません。
結論

コメントを含める場所の例と、避けるべきことに関するいくつかの提案を提供しましたが、コードにコメントをフォーマットする方法については難しくて高速なルールはありません。行、単語、または含めるべき情報の数はあなた次第であるか、あなたとあなたの仲間の間で決定することができます。フォーマットを一貫性に保つ限り、それは物事を整頓し、他の人がコードを使用して同じことをするように奨励します。

開発プロセスの一部にコメントを作成することに関連する多くの利点があります。特に同じファイルで作業している人が多い場合は、自分が適切だと思われる場所に含める習慣に入るのは良いことです。また、ガイドラインの外部ドキュメントではなく、メッセージやプル要求などのワークフローに組み込まれた他の形式のドキュメントを検討するのにも役立ちます。

コメントのコメントに関するガイドラインに従っていますか？または、異なるが効果的なドキュメントを持っている会社で働いていますか？

HTMLおよびCSSコメント

に関するよくある質問（FAQ）

HTMLおよびCSSでコメントを使用することの重要性は何ですか？ HTMLとCSSでコードをコメントするにはどうすればよいですか？

。たとえば、

。 CSSでは、 /*と

/の間にテキストを包むことでコメントが行われます。たとえば、 /

これはコメントです * /。

コメントは私のウェブサイトのパフォーマンスに影響を与えることができますか？それらは、レンダリングプロセス中にブラウザによって無視されます。ただし、過度のコメントはファイルサイズを増やす可能性があり、これは荷重時間にわずかに影響する可能性があります。簡潔でありながら記述的であり、コードの複雑なまたは重要なセクションについてコメントし、不必要または冗長なコメントを回避します。また、コードの変更を反映してコメントを定期的に更新することも良い習慣です。コメントを使用して特定のブラウザからコードを非表示にできますか？特定のブラウザ。条件付きコメントとして知られるこの手法は、インターネットエクスプローラーのさまざまなバージョンに異なるスタイルまたはスクリプトを提供するためによく使用されます。コードの特定の部分を一時的に無効にすることにより。これにより、コードの問題のあるセクションを隔離して特定できます。

htmlとcssにコメントをネストできますか？そうしようとすると、予期しない結果が生じる可能性があります。 CSSでは、コメントをネストすることができますが、コードを読み取りや理解しにくくすることができるため、一般的に推奨されません。 >シングルラインコメントは、短い説明または注釈に使用されますが、マルチラインコメントは、長い説明またはコードブロックに使用されます。 HTMLでは、すべてのコメントは技術的にマルチラインです。 CSSでは、シングルラインのコメントは//で始まり、行の最後で終了しますが、マルチラインのコメントは / *で始まり、 * /。
で終了します。コメントで特殊文字を使用できますか？
はい、コメントで特殊文字を使用できます。ただし、HTMLでは、コメントが早期に終了する可能性があるため、コメントの中で「 - 」の使用を避けないでください。

コメントを使用してコードの読みやすさを改善するにはどうすればよいですか？

コメントは、説明と注釈を提供することにより、コードの読みやすさを改善できます。また、コードのさまざまなセクションを分離するために使用して、ナビゲートしやすくすることもできます。ただし、コメントと過剰コメントのバランスをとることが重要です。コメントが多すぎると、コードが乱雑になり、読みにくくなります。

以上があなたのHTMLとCSSのコメントはどれくらい良いですか？の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。