すべてのコードの全般的なガイドライン

以下のコード例のガイドラインは、 HTML, CSS, JavaScript, その他のどれであっても適用されます。

• インデントづけ、領域、大きさ
  • インデント付け
  • コードの行の長さ
  • コードブロックの高さ
• 例を示す場合のガイドライン
  • 例を表示する大きさ
  • 画像およびその他のメディアの使用
  • 色の使用
  • 良い例と悪い例の強調表示
• リファレンスページの構文の節を書く

すべてのコードは、次のように2文字のインデントを使用します。

<div>
  <p>This is my paragraph.</p>
</div>

function myFunc() {
  if(thingy) {
    console.log('Yup, that worked.');
  }
}

コードの行の長さは最大80文字 (対話型デモの場合は64文字) にしてください。読みやすくするために、適切な方法で改行する必要がありますが、ベストプラクティスを犠牲にする必要はありません。

例えば、次のものは良くありません。

let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.';

次のものはましですが、まだ幾らかぎこちないです。

let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign '
+ 'matter may have nestled its way into his mighty throat. Many a fat alley rat '
+ 'had met its demise while staring point blank down the cavernous barrel of '
+ 'this awesome prowling machine.';

テンプレートリテラルを使うのもよいでしょう。

let tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign
  matter may have nestled its way into his mighty throat. Many a fat alley rat
  had met its demise while staring point blank down the cavernous barrel of
  this awesome prowling machine.`;

コードブロックは必要なだけの長さであるべきですが、それより長くなってもいけません。できれば、15-25行が目安です。コードブロックがはるかに長くなりそうであれば、最も有用なスニペットのみを示し、 GitHup リポジトリや codepen に入れた完全な例にリンクさせてください。

MDN のメインコンテンツペインは、デスクトップでおよそ 700px の幅ですので、 MDN に埋め込む例はその幅であれば大丈夫です (埋め込む例の幅を 100% に設定してください)。

高さについては、可能な限り画面で読みやすくするために、例を表示する高さを 700px 未満に保つことをお勧めします。

また、サンプルをある程度レスポンシブにすることを検討する必要があり、そうすればモバイル端末でも役立ちます。

画像やその他のメディアを例に含めたい場合があるでしょう。その場合は次のようにしてください。

• あなたが利用できるライセンスであることを確認してください。許容度がとても広いライセンス、例えば CC0 や、一般的なコンテンツライセンス — クリエイティブ・コモンズの表示-継承ライセンス (CC-BY-SA) — と互換性のある1つ以上のライセンスを持つメディアを使用してみてください。
• 画像については、 https://tinypng.com や https://imageoptim.com を通すと例のページの重さを軽減することができます。
• SVG については、コードを SVGOMG に通すと SVG ファイルの最後に空行があることを保証することができます。

• ページ上にアイコンを表示するときは (例えば background-image などで)、適切な箇所に MDN 組み込みアイコンを使用し、他のものとスタイルを合わせるようにしてください。

16進数であれば小文字で、影や主な色 (black, white, red など) ならばキーワードを使用することもできます。より複雑な方式 (透過を含めるなど) は必要な場合だけ使用してください。

下記のように、主要な色やその他の「基本的な」色はキーワードを使用することを推奨します。

color: black;
color: white;
color: red;

もっと複雑な色には rgb() を使用してください (半透過のものも含む)。

color: rgb(0, 0, 0, 0.5);
color: rgb(248, 242, 230);

16進の色を使用する必要がある場合は、小文字を使用してください。

color: #058ed9;
color: #a39a92;

冗長であれば短縮形を使用してください。

color: #ff0;
color: #fff;

MDN's Fiori guidelines (フロンドエンドコードベース向け) には、 MDN のデザイン全般を貫く有用な色のセットがあります。

このガイドラインを見ていてお気づきと思いますが、良い方法と思われるコードブロックは緑地に笑顔で強調表示され、悪い方法と思われるコードブロックには赤地に悲しい顔で強調表示されています。

これを行うには、まず MDN エディターコントロールを使用してコードブロックを <pre> ブロックの中に入れ、適切な構文強調表示を指定してください。コードのソースは次のようになります。

<pre class="brush: js">
function myFunc() {
  console.log('Hello!');
};</pre>

これを良い例とするには、 example-good を class 属性の引用符の直前に入れてください。

<pre class="brush: js example-good">
  ...

悪い例とするには、 example-bad を class 属性の引用符の直前に入れてください。

<pre class="brush: js example-bad">
  ...

これらの使用をお勧めします。これらをすべての場所で使用する必要はありません。特に、コードの良い点と悪い点を明確に示している場合に限って使用してください。

MDN リファレンスページには、ある機能、例えば JavaScript メソッド、 CSS プロパティ、 HTML 要素、などがどのような構文を取りうる・取るべきかを曖昧にせずに示します。これらを記述するガイドラインは構文の節の文書にあります。