CSSガイドライン、パート2。コードに関するコメント

各プロジェクトには特定のニュアンスと微妙さがあり、誰もが覚えているわけではありません。開発者に起こりうる最悪の事態は、彼が書いていないコードで作業していることです。 自分のコードの複雑さを覚えていても、他の誰かのコードはもちろんのこと、ある程度まで可能です。 そのため、 CSSについてコメントする必要があります 。



CSSは宣言型言語であり、理解するのが難しいことがよくあります。

• コードの一部が別の部分に依存していること。
• コードの特定の部分の変更を伴う効果。
• 他のどこで新しい問題なくコードを使用できますか。
• 特定の要素が継承するスタイル。
• 無視できるスタイル。
• 開発者がコードを使用する予定の場所。

このリストは、 transform



プロパティを使用してハードウェアアクセラレーションを有効にするなど、多くのCSSの癖にも触れていませんが、そのようなことはコードの機能の理解を複雑にします。



CSSだけでは十分に明確でない可能性があるため、開発者はコードにコメントすることで本当に恩恵を受けます。



原則として、開発者がコンテキストから外した場合に理解できないコードの部分についてコメントする必要があります。 color: red;



あることをメモする必要はありませんcolor: red;



テキストを赤にします。 ただし、たとえば、 overflow: hidden;



プロパティを使用する場合overflow: hidden;



フロートをクリアし、ブロック外のコンテンツを非表示にしないようにするには、説明コメントを追加する必要があります。

高レベルのコメント

セクションまたはコンポーネント全体を説明する大きなコメントには、80文字の行ルールに準拠したDocBlockのような複数行コメントを使用します。



以下に、CSSWizardy Webサイトのヘッダーコードにコメントする実際の例を見ることができます。

 /** * The site's main page-head can have two different states: * * 1) Regular page-head with no backgrounds or extra treatments; it just * contains the logo and nav. * 2) A masthead that has a fluid-height (becoming fixed after a certain point) * which has a large background image, and some supporting text. * * The regular page-head is incredibly simple, but the masthead version has some * slightly intermingled dependency with the wrapper that lives inside it. */
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このレベルのコメントは、一般的に要素を説明するために使用する必要があります。その状態、この状態が何に依存しているかなどです。

スタイルの継承の表示

多数のファイルを操作する場合、相互に関連するルールセットが常に同じファイルにあるとは限りません。 たとえば、ボタンの基本スタイル（サイズやインデントなど）のみを含むメインクラス.btn



がある場合があります。 このクラスはコンポーネントファイルで展開され、必要な外観を与えるためにスタイルが追加されます。 スタイルの継承を示すことにより、オブジェクト間のこれらの関係を識別する必要があります。



たとえば、メインクラス（オブジェクト）を持つファイルでは：

 /** * Extend `.btn {}` in _components.buttons.scss. */ .btn {}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

子クラスを含むファイル内：

 /** * These rules extend `.btn {}` in _objects.buttons.scss. */ .btn--positive {} .btn--negative {}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

このようなコードへのコメントは開発者の多大な労力を必要としません。これらのコメントのおかげで、コードを操作しなければならない人はクラス間の関係を簡単に把握できます。

低レベルのコメント

多くの場合、プロパティの宣言を使用して特定のコード行にコメントする必要があります。 このために、脚注を使用します。 リンクを使用すると、前述のサイトのヘッダーコードに関するより複雑なコメントの例を見ることができます。 このコメント方法により、すべてのドキュメントを1か所にまとめて、コード内に長いコメントを直接記述する代わりに、ドキュメント内の正しい場所を参照することができます。

プリプロセッサとコメント

すべてではありませんが、多くのプリプロセッサでは、コンパイル時に最終スタイルシートに出力されないコメントを追加することができます。 コンパイルされないコードにもこのようなコメントを使用することをルールにします。 最終ファイルに出力されるコードには、通常のコメントを使用します。



そうです：

 // Dimensions of the @2x image sprite: $sprite-width: 920px; $sprite-height: 212px; /** * 1. Default icon size is 16px. * 2. Squash down the retina sprite to display at the correct size. */ .sprite { width: 16px; /* [1] */ height: 16px; /* [1] */ background-image: url(/img/sprites/main.png); background-size: ($sprite-width / 2 ) ($sprite-height / 2); /* [2] */ }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

この例では、プリプロセッサコメントを使用して変数（コンパイルされない）を文書化し、通常のコードでは標準のコメント方法を使用しました。 この方法により、コンパイルされたCSSファイルには、関連する関連情報のみが含まれるようになります。

コメントを削除する

本番環境でコードを使用する場合は、コメントをすべて削除し、CSS自体を展開前に縮小する必要があることに注意してください。



前のパート： CSSガイドライン、パート1。構文とフォーマット

次のパート： CSSガイドライン、パート3。クラスの命名