initial commit

4 files changed, 660 insertions, 0 deletions

diff --git a/files/ja/mdn/guidelines/code_guidelines/css/index.html b/files/ja/mdn/guidelines/code_guidelines/css/index.html
new file mode 100644
index 0000000000..4f4449ba5c
--- /dev/null
+++ b/files/ja/mdn/guidelines/code_guidelines/css/index.html
@@ -0,0 +1,255 @@
+---
+title: CSS のガイドライン
+slug: MDN/Guidelines/Code_guidelines/CSS
+tags:
+  - CSS
+  - Code
+  - Guide
+  - Guidelines
+  - MDN Meta
+translation_of: MDN/Guidelines/Code_guidelines/CSS
+---
+<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div>
+
+<p class="summary">次のガイドラインでは、MDN コードの例として CSS を記述する方法について説明します。</p>
+
+<h2 id="In_this_article" name="In_this_article">目次</h2>
+
+<ul>
+ <li><a href="#High-level_guidelines">高水準のガイドライン</a>
+
+  <ul>
+   <li><a href="#Dont_use_preprocessors">プリプロセッサーを使用しない</a></li>
+   <li><a href="#Dont_use_specific_CSS_methodologies">特定の CSS の方法論を使わない</a></li>
+   <li><a href="#Use_flexiblerelative_units">柔軟性のある/相対的な単位を使用する</a></li>
+   <li><a href="#Dont_use_resets">リセットを使わない</a></li>
+   <li><a href="#Plan_your_CSS_%E2%80%94_avoid_overriding">CSS を計画する - オーバーライドを避ける</a></li>
+  </ul>
+ </li>
+ <li><a href="#General_CSS_coding_style">一般的な CSS コーディングスタイル</a>
+  <ul>
+   <li><a href="#Use_expanded_syntax">展開した構文を使用する</a></li>
+   <li><a href="#Favor_longhand_rules_over_terse_shorthand">一括指定よりも個別指定を推奨</a></li>
+   <li><a href="#Use_double_quotes_around_values">値の周りには二重引用符を使用する</a></li>
+   <li><a href="#Spacing_around_function_parameters">関数の引数の空白</a></li>
+   <li><a href="#CSS_comments">CSS のコメント</a></li>
+   <li><a href="#Dont_use_!important">!important は使わない</a></li>
+  </ul>
+ </li>
+ <li><a href="#Specific_CSS_syntax_points">具体的な CSS 構文のポイント</a>
+  <ul>
+   <li><a href="#Turning_off_borders_and_other_properties">ボーダーなどのプロパティをオフにする</a></li>
+   <li><a href="#Use_mobile_first_media_queries">「モバイルファースト」のメディアクエリを使用する</a></li>
+  </ul>
+ </li>
+ <li><a href="#Selectors">セレクター</a>
+  <ul>
+   <li><a href="#Dont_use_ID_selectors">ID セレクターを使わない</a></li>
+   <li><a href="#Put_multiple_selectors_on_separate_lines">複数のセレクターは個別の行に配置する</a></li>
+  </ul>
+ </li>
+</ul>
+
+<h2 id="High-level_guidelines" name="High-level_guidelines">高水準のガイドライン</h2>
+
+<h3 id="Dont_use_preprocessors" name="Dont_use_preprocessors">プリプロセッサーを使用しない</h3>
+
+<p>MDN のサンプル コードでは、<a href="https://sass-lang.com/">Sass</a>,<a href="http://lesscss.org/">Less</a>,<a href="http://stylus-lang.com/">Stylus,</a>などのプリプロセッサー構文を使用しないでください。MDN はバニラ CSS 言語を文書化しており、プリプロセッサーを使用することは、例を理解するためのハードルを上げるだけであり、読者を混乱させる可能性があります。</p>
+
+<h3 id="Dont_use_specific_CSS_methodologies" name="Dont_use_specific_CSS_methodologies">特定の CSS の方法論を使わない</h3>
+
+<p>前のガイドラインと同じ精神で、 <a href="http://getbem.com/naming/">BEM</a> や <a href="https://smacss.com/">SMACSS</a> のような特定の CSS の方法論を使って MDN のサンプルコードを書かないようにしてください。これらが有効な CSS 構文であっても、それらの方法論に精通していない人にとっては、命名規則が混乱を招く可能性があります。</p>
+
+<h3 id="Use_flexiblerelative_units" name="Use_flexiblerelative_units">柔軟性のある/相対的な単位を使用する</h3>
+
+<p>可能な限り幅広い端末で最大限の柔軟性を実現するために、コンテナーやパディングなどの寸法は、em や rem のような相対的な単位を使用し、ビューポートの幅に応じて変化させたい場合はパーセント値やビューポートの単位を使用することをお勧めします。これについては、<a href="/ja/docs/Web/Apps/app_layout/responsive_design_building_blocks#Fluid_grids">レスポンシブデザインのビルディングブロック</a>の記事をご覧ください。</p>
+
+<h3 id="Dont_use_resets" name="Dont_use_resets">リセットを使わない</h3>
+
+<p>For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world CSS resets can be overkill, resulting in lots of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc.</p>
+
+<p>If you really feel like you need to use a reset, consider using <a href="http://necolas.github.io/normalize.css/">normalize.css by Nicolas Gallagher</a>, which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on <code>&lt;body&gt;</code>, for example) and fix a few bugs.</p>
+
+<h3 id="Plan_your_CSS_—_avoid_overriding" name="Plan_your_CSS_—_avoid_overriding">CSS を計画する — オーバーライドを避ける</h3>
+
+<p>Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to avoid too much overriding. If you keep finding yourself writing styles and then cancelling them again a few rulesets down, you probably need to rethink your strategy.</p>
+
+<h2 id="General_CSS_coding_style" name="General_CSS_coding_style">一般的な CSS のコーディングスタイル</h2>
+
+<h3 id="Use_expanded_syntax" name="Use_expanded_syntax">展開した構文を使用する</h3>
+
+<p>There are a variety of CSS writing styles you can use, but we prefer the expanded style, with the selector/opening brace, close brace, and each declaration on a separate line. This maximizes readability, and again, promotes consistency on MDN.</p>
+
+<p>Use this:</p>
+
+<pre class="brush: css example-good notranslate">p {
+  color: white;
+  background-color: black;
+  padding: 1rem;
+}</pre>
+
+<p>Not this:</p>
+
+<pre class="brush: css example-bad notranslate">p { color: white; background-color: black; padding: 1rem; }</pre>
+
+<p>In addition, keep these specifics in mind:</p>
+
+<ul>
+ <li>Include a space between the selector(s) and the opening curly brace.</li>
+ <li>Always include a semi-colon at the end of the last declaration, even though it isn't strictly necessary.</li>
+ <li>Put the closing curly brace on a new line.</li>
+ <li>In each declaration, put a space after the separating colon, but not before.</li>
+ <li>Use 2 spaces for code indentation.</li>
+</ul>
+
+<h3 id="Favor_longhand_rules_over_terse_shorthand" name="Favor_longhand_rules_over_terse_shorthand">一括指定よりも個別指定を推奨</h3>
+
+<p>Usually when teaching the specifics of CSS syntax, it is clearer and more obvious to use longhand properties, rather than terse shorthand (unless of course teaching the shorthand is the point of the example). Remember that the point of MDN examples is to teach people, not to be clever or efficient.</p>
+
+<p>To start with, it is often harder to understand what the shorthand is doing. It takes a while to pick apart exactly what {{cssxref("font")}} syntax is doing, for example:</p>
+
+<pre class="brush: css notranslate">font: small-caps bold 2rem/1.5 sans-serif;</pre>
+
+<p>Whereas this is more immediate in terms of understanding:</p>
+
+<pre class="brush: css notranslate">font-variant: small-caps;
+font-weight: bold;
+font-size: 2rem;
+line-height: 1.5;
+font-family: sans-serif;</pre>
+
+<p>Second, CSS shorthand comes with potential added pitfalls — default values are set for parts of the syntax that you don't explicitly set, which can produce unexpected resets of values you've set earlier in the cascade, or other expected effects. The {{cssxref("grid")}} property for example sets all of the following default values for items that are not specified:</p>
+
+<ul>
+ <li>{{cssxref("grid-template-rows")}}: <code>none</code></li>
+ <li>{{cssxref("grid-template-columns")}}: <code>none</code></li>
+ <li>{{cssxref("grid-template-areas")}}: <code>none</code></li>
+ <li>{{cssxref("grid-auto-rows")}}: <code>auto</code></li>
+ <li>{{cssxref("grid-auto-columns")}}: <code>auto</code></li>
+ <li>{{cssxref("grid-auto-flow")}}: <code>row</code></li>
+ <li>{{cssxref("grid-column-gap")}}: <code>0</code></li>
+ <li>{{cssxref("grid-row-gap")}}: <code>0</code></li>
+ <li>{{cssxref("column-gap")}}: <code>normal</code></li>
+ <li>{{cssxref("row-gap")}}: <code>normal</code></li>
+</ul>
+
+<p>In addition, some shorthands only work as expected if you include the different value components in a certain order. In CSS animations for example:</p>
+
+<pre class="brush: css notranslate">/* duration | timing-function | delay | iteration-count
+   direction | fill-mode | play-state | name */
+animation: 3s ease-in 1s 2 reverse both paused slidein;</pre>
+
+<p>As an example, the first value that can be parsed as a {{cssxref("time", "&lt;time&gt;")}} is assigned to the {{cssxref("animation-duration")}}, and the second one is assigned to {{cssxref("animation-delay")}}. For more details, read the full <a href="/en-US/docs/Web/CSS/animation#Syntax">animation syntax</a> details.</p>
+
+<h3 id="Use_double_quotes_around_values" name="Use_double_quotes_around_values">値の周りには二重引用符を使用する</h3>
+
+<p>Where quotes can or should be included, use them, and use double quotes. For example:</p>
+
+<pre class="brush: css example-good notranslate">[data-vegetable="liquid"] {
+  background-color: goldenrod;
+  background-image: url("../../media/examples/lizard.png");
+}</pre>
+
+<h3 id="Spacing_around_function_parameters" name="Spacing_around_function_parameters">関数の引数の空白</h3>
+
+<p>Function parameters should have spaces after their separating commas, but not before:</p>
+
+<pre class="brush: css example-good notranslate">color: rgb(255, 0, 0);
+background-image: linear-gradient(to bottom, red, black);</pre>
+
+<h3 id="CSS_のコメント">CSS のコメント</h3>
+
+<p>Use CSS-style comments to comment code that isn't self-documenting:</p>
+
+<pre class="brush: css example-good notranslate">/* This is a CSS-style comment */</pre>
+
+<p>Put your comments on separate lines preceeding the code they are referring to:</p>
+
+<pre class="brush: css example-good notranslate">h3 {
+  /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */
+  text-shadow: 1px 1px 2px red;
+  /* Sets the font-size to double the default document font size */
+  font-size: 2rem;
+}</pre>
+
+<p>Also note that you should leave a space between the asterisks and the comment, in each case.</p>
+
+<h3 id="Dont_use_!important" name="Dont_use_!important">!important は使わない</h3>
+
+<p>!important is a last resort generally only used when you need to override something and there is no other way. It is a bad practice and you should avoid it wherever possible.</p>
+
+<p>Bad:</p>
+
+<pre class="brush: css example-bad notranslate">.bad-code {
+  font-size: 4rem !important;
+}</pre>
+
+<h2 id="Specific_CSS_syntax_points" name="Specific_CSS_syntax_points">具体的な CSS 構文のポイント</h2>
+
+<h3 id="border_などのプロパティをオフにする">border などのプロパティをオフにする</h3>
+
+<p>When turning off borders (and any other properties that can take <code>0</code> or <code>none</code> as values), use <code>0</code> rather than <code>none</code>:</p>
+
+<pre class="brush: css example-good notranslate">border: 0;</pre>
+
+<h3 id="Use_mobile_first_media_queries" name="Use_mobile_first_media_queries">「モバイルファースト」のメディアクエリを使用する</h3>
+
+<p>When including different sets of styles for different target viewport sizes using media queries inside the same stylesheet, it is a good idea to make the default styling before any media queries have been applied to the document the narrow screen/mobile styling, and then override this for wider viewports inside successive media queries.</p>
+
+<pre class="brush: css example-good notranslate">/*Default CSS layout for narrow screens*/
+
+@media (min-width: 480px) {
+  /*CSS for medium width screens*/
+}
+
+@media (min-width: 800px) {
+  /*CSS for wide screens*/
+}
+
+@media (min-width: 1100px) {
+  /*CSS for really wide screens*/
+}</pre>
+
+<p>This has many advantages, outlined in our <a href="/en-US/docs/Web/Apps/Progressive/Responsive/Mobile_first">Mobile First</a> article.</p>
+
+<h2 id="Selectors" name="Selectors">セレクター</h2>
+
+<h3 id="Dont_use_ID_selectors" name="Dont_use_ID_selectors">ID セレクターを使わない</h3>
+
+<p>There is really no need to use ID selectors — they are less flexible (you can't add more if you discover you need more than one), and are harder to override if needed, being of a higher specificity than classes.</p>
+
+<p>Good:</p>
+
+<pre class="brush: css example-good notranslate">.editorial-summary {
+  ...
+}</pre>
+
+<p>Bad:</p>
+
+<pre class="brush: css example-bad notranslate">#editorial-summary {
+  ...
+}</pre>
+
+<h3 id="Put_multiple_selectors_on_separate_lines" name="Put_multiple_selectors_on_separate_lines">複数のセレクターは個別の行に配置する</h3>
+
+<p>When a rule has multiple selectors, put each selector on a new line. This makes the selector list easier to read, and can help to make code lines shorter.</p>
+
+<p>Do this:</p>
+
+<pre class="brush: css example-good notranslate">h1,
+h2,
+h3 {
+  font-family: sans-serif;
+  text-align: center;
+}</pre>
+
+<p>Not this:</p>
+
+<pre class="brush: css example-bad notranslate">h1, h2, h3 {
+  font-family: sans-serif;
+  text-align: center;
+}</pre>
+
+<h2 id="Good_CSS_examples_on_MDN" name="Good_CSS_examples_on_MDN">MDN の良い CSS の例</h2>
+
+<p>CSS プロパティのリファレンスページの冒頭には、簡潔で意味のある良い CSS スニペットが掲載されています。 <a href="/ja/docs/Web/CSS/Reference#Keyword_index">CSS のキーワード索引</a>から探して参照してみてください。そこにあるインタラクティブな例は、一般的に上記のガイドラインに沿って書かれていますが、ガイドラインが新しく書かれる前に書かれたものがほとんどなので、場所によってはそうではない場合があることに注意してください。</p>
diff --git a/files/ja/mdn/guidelines/code_guidelines/general/index.html b/files/ja/mdn/guidelines/code_guidelines/general/index.html
new file mode 100644
index 0000000000..207830b455
--- /dev/null
+++ b/files/ja/mdn/guidelines/code_guidelines/general/index.html
@@ -0,0 +1,160 @@
+---
+title: すべてのコードの全般的なガイドライン
+slug: MDN/Guidelines/Code_guidelines/General
+tags:
+  - Code
+  - General
+  - Guide
+  - Guidelines
+  - MDN Meta
+  - MDN メタ
+  - ガイド
+  - ガイドライン
+  - コード
+  - 全般
+translation_of: MDN/Guidelines/Code_guidelines/General
+---
+<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div>
+
+<p class="summary">以下のコード例のガイドラインは、 HTML, CSS, JavaScript, その他のどれであっても適用されます。</p>
+
+<h2 id="In_this_article" name="In_this_article">目次</h2>
+
+<ul>
+ <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Indentation_spacing_size">インデントづけ、領域、大きさ</a>
+
+  <ul>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Indentation">インデント付け</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Code_line_length">コードの行の長さ</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Code_block_height">コードブロックの高さ</a></li>
+  </ul>
+ </li>
+ <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Guidelines_for_displaying_examples">例を示す場合のガイドライン</a>
+  <ul>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Size_of_rendered_example">例を表示する大きさ</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Use_of_images_and_other_media">画像およびその他のメディアの使用</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Use_of_color">色の使用</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Highlight_good_and_bad_practice_examples">良い例と悪い例の強調表示</a></li>
+  </ul>
+ </li>
+ <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Writing_syntax_sections_on_reference_pages">リファレンスページの構文の節を書く</a></li>
+</ul>
+
+<h2 id="Indentation_spacing_size" name="Indentation_spacing_size">インデント付け、領域、大きさ</h2>
+
+<h3 id="Indentation" name="Indentation">インデント付け</h3>
+
+<p>すべてのコードは、次のように2文字のインデントを使用します。</p>
+
+<pre class="brush: html example-good notranslate">&lt;div&gt;
+  &lt;p&gt;This is my paragraph.&lt;/p&gt;
+&lt;/div&gt;</pre>
+
+<pre class="brush: js example-good notranslate">function myFunc() {
+  if(thingy) {
+    console.log('Yup, that worked.');
+  }
+}</pre>
+
+<h3 id="Code_line_length" name="Code_line_length">コードの行の長さ</h3>
+
+<p>コードの行の長さは最大80文字 (<a href="https://github.com/mdn/interactive-examples">対話型デモ</a>の場合は64文字) にしてください。読みやすくするために、適切な方法で改行する必要がありますが、ベストプラクティスを犠牲にする必要はありません。</p>
+
+<p>例えば、次のものは良くありません。</p>
+
+<pre class="brush: js example-bad notranslate">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.';</pre>
+
+<p>次のものはましですが、まだ幾らかぎこちないです。</p>
+
+<pre class="brush: js notranslate">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.';</pre>
+
+<p>テンプレートリテラルを使うのもよいでしょう。</p>
+
+<pre class="brush: js example-good notranslate">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.`;</pre>
+
+<h3 id="Code_block_height" name="Code_block_height">コードブロックの高さ</h3>
+
+<p>コードブロックは必要なだけの長さであるべきですが、それより長くなってもいけません。できれば、15-25行が目安です。コードブロックがはるかに長くなりそうであれば、最も有用なスニペットのみを示し、 GitHup リポジトリや codepen に入れた完全な例にリンクさせてください。</p>
+
+<h2 id="Guidelines_for_displaying_examples" name="Guidelines_for_displaying_examples">例を表示する際のガイドライン</h2>
+
+<h3 id="Size_of_rendered_example" name="Size_of_rendered_example">例を表示する大きさ</h3>
+
+<p>MDN のメインコンテンツペインは、デスクトップでおよそ 700px の幅ですので、 MDN に埋め込む例はその幅であれば大丈夫です (埋め込む例の幅を 100% に設定してください)。</p>
+
+<p>高さについては、可能な限り画面で読みやすくするために、例を表示する高さを 700px 未満に保つことをお勧めします。</p>
+
+<p>また、サンプルをある程度レスポンシブにすることを検討する必要があり、そうすればモバイル端末でも役立ちます。</p>
+
+<h3 id="Use_of_images_and_other_media" name="Use_of_images_and_other_media">画像およびその他のメディアの使用</h3>
+
+<p>画像やその他のメディアを例に含めたい場合があるでしょう。その場合は次のようにしてください。</p>
+
+<ul>
+ <li>あなたが利用できるライセンスであることを確認してください。許容度がとても広いライセンス、例えば <a href="https://creativecommons.org/share-your-work/public-domain/cc0/" rel="nofollow">CC0</a> や、一般的なコンテンツライセンス — <a class="external text external-icon" href="http://creativecommons.org/licenses/by-sa/2.5/" rel="nofollow noopener" title="http://creativecommons.org/licenses/by-sa/2.5/">クリエイティブ・コモンズの表示-継承ライセンス</a> (CC-BY-SA) — と互換性のある1つ以上のライセンスを持つメディアを使用してみてください。</li>
+ <li>画像については、 <a href="https://tinypng.com" rel="nofollow">https://tinypng.com</a> や <a href="https://imageoptim.com" rel="nofollow">https://imageoptim.com</a> を通すと例のページの重さを軽減することができます。</li>
+ <li><code>SVG</code> については、コードを <a href="https://jakearchibald.github.io/svgomg/">SVGOMG</a> に通すと <code>SVG</code> ファイルの最後に空行があることを保証することができます。</li>
+ <li>
+  <p>ページ上にアイコンを表示するときは (例えば {{cssxref("background-image")}} などで)、適切な箇所に <a href="https://mdn.github.io/mdn-fiori/patterns/css/iconography/">MDN 組み込みアイコン</a>を使用し、他のものとスタイルを合わせるようにしてください。</p>
+ </li>
+</ul>
+
+<h3 id="Use_of_color" name="Use_of_color">色の使用</h3>
+
+<p>16進数であれば小文字で、影や主な色 (black, white, red など) ならばキーワードを使用することもできます。より複雑な方式 (透過を含めるなど) は必要な場合だけ使用してください。</p>
+
+<p>下記のように、主要な色やその他の「基本的な」色はキーワードを使用することを推奨します。</p>
+
+<pre class="brush: css example-good notranslate">color: black;
+color: white;
+color: red;</pre>
+
+<p>もっと複雑な色には rgb() を使用してください (半透過のものも含む)。</p>
+
+<pre class="brush: css example-good notranslate">color: rgb(0, 0, 0, 0.5);
+color: rgb(248, 242, 230);</pre>
+
+<p>16進の色を使用する必要がある場合は、小文字を使用してください。</p>
+
+<pre class="brush: css example-good notranslate">color: #058ed9;
+color: #a39a92;</pre>
+
+<p>冗長であれば短縮形を使用してください。</p>
+
+<pre class="brush: css example-good notranslate">color: #ff0;
+color: #fff;</pre>
+
+<p><a href="https://mdn.github.io/mdn-fiori/">MDN's Fiori guidelines</a> (フロンドエンドコードベース向け) には、 MDN のデザイン全般を貫く<a href="https://mdn.github.io/mdn-fiori/patterns/scss/variables/">有用な色のセット</a>があります。</p>
+
+<h3 id="Highlight_good_and_bad_practice_examples" name="Highlight_good_and_bad_practice_examples">良い例と悪い例の強調表示</h3>
+
+<p>このガイドラインを見ていてお気づきと思いますが、良い方法と思われるコードブロックは緑地に笑顔で強調表示され、悪い方法と思われるコードブロックには赤地に悲しい顔で強調表示されています。</p>
+
+<p>これを行うには、まず MDN エディターコントロールを使用してコードブロックを <code>&lt;pre&gt;</code> ブロックの中に入れ、適切な構文強調表示を指定してください。コードのソースは次のようになります。</p>
+
+<pre class="notranslate">&lt;pre class="brush: js"&gt;
+function myFunc() {
+  console.log('Hello!');
+};&lt;/pre&gt;</pre>
+
+<p>これを良い例とするには、 <code>example-good</code> を <code>class</code> 属性の引用符の直前に入れてください。</p>
+
+<pre class="notranslate">&lt;pre class="brush: js example-good"&gt;
+  ...</pre>
+
+<p>悪い例とするには、 <code>example-bad</code> を <code>class</code> 属性の引用符の直前に入れてください。</p>
+
+<pre class="notranslate">&lt;pre class="brush: js example-bad"&gt;
+  ...</pre>
+
+<p>これらの使用をお勧めします。これらをすべての場所で使用する必要はありません。特に、コードの良い点と悪い点を明確に示している場合に限って使用してください。</p>
+
+<h2 id="Writing_syntax_sections_on_reference_pages" name="Writing_syntax_sections_on_reference_pages">リファレンスページの構文の節を書く</h2>
+
+<p>MDN リファレンスページには、ある機能、例えば JavaScript メソッド、 CSS プロパティ、 HTML 要素、などがどのような構文を取りうる・取るべきかを曖昧にせずに示します。これらを記述するガイドラインは<a href="/ja/docs/MDN/Contribute/Structures/Syntax_sections">構文の節</a>の文書にあります。</p>
diff --git a/files/ja/mdn/guidelines/code_guidelines/html/index.html b/files/ja/mdn/guidelines/code_guidelines/html/index.html
new file mode 100644
index 0000000000..167160be4b
--- /dev/null
+++ b/files/ja/mdn/guidelines/code_guidelines/html/index.html
@@ -0,0 +1,165 @@
+---
+title: HTML ガイドライン
+slug: MDN/Guidelines/Code_guidelines/HTML
+tags:
+  - Code
+  - Guide
+  - Guidelines
+  - HTML
+  - MDN Meta
+translation_of: MDN/Guidelines/Code_guidelines/HTML
+---
+<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div>
+
+<p class="summary">以下のガイドラインでは、MDN のコードの例で HTML をどのように記述するのかを学習します。</p>
+
+<h2 id="In_this_article" name="In_this_article">この記事について</h2>
+
+<ul>
+ <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Doctype_and_metadata">文書型宣言とメタデータ</a>
+
+  <ul>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Doctype">Doctype</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Document_language">文書の言語</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Document_characterset">文書の文字セット</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Viewport_meta_tag">ビューポートメタタグ</a></li>
+  </ul>
+ </li>
+ <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#General_markup_coding_style">一般的なマークアップコーディングスタイル</a>
+  <ul>
+   <li><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Use_lowercase">小文字を使う</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Trailing_slashes">末尾のスラッシュ</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Quoting_attributes">属性の引用</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Use_double_quotes">ダブルクォートを使う</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Boolean_attributes">真偽属性</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Class_and_ID_names">クラス と ID の名前</a></li>
+   <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Entity_references">実体参照</a></li>
+  </ul>
+ </li>
+</ul>
+
+<h2 id="Doctype_and_metadata" name="Doctype_and_metadata">Doctype とメタデータ</h2>
+
+<div class="note">
+<p><strong>注記</strong>: このセクションにあるガイドラインは完全な HTML 文書として見せなければならない時だけ適用してください。多くの場合、このようにする必要がありません; スニペット(HTML の断片)で通常は機能を説明するのに十分間に合います。<a href="/ja/docs/MDN/Contribute/Structures/Code_examples#Traditional_live_samples">EmbedLiveSample macro</a> を使うと、スニペットを取り込みます; 表示される際に自動で完全な HTML 文書に挿入されます。</p>
+</div>
+
+<h3 id="Doctype" name="Doctype">Doctype</h3>
+
+<p>HTML5 の Doctype を使わなくてはなりません。短く、覚えやすく、後方互換性があります:</p>
+
+<pre class="brush: html example-good notranslate">&lt;!DOCTYPE html&gt;</pre>
+
+<h3 id="Document_language" name="Document_language">文書の言語</h3>
+
+<p>{{htmlelement("html")}} 要素に {{htmlattrxref('lang')}} 属性を使って文書の言語を設定します:</p>
+
+<pre class="brush: html example-good notranslate">&lt;html lang="ja"&gt;</pre>
+
+<p>これはアクセシビリティと検索エンジンにとって良いことで、コンテンツのローカライズに役立ち、最良の慣習を使うべきと気づかせます。</p>
+
+<h3 id="Document_characterset" name="Document_characterset">文書の文字セット</h3>
+
+<p>また文書の文字セットを以下のように定義しなければなりません:</p>
+
+<pre class="brush: html example-good notranslate">&lt;meta charset="utf-8"&gt;</pre>
+
+<p>UTF-8 を使用しないというとても明白な理由がない限りは使用するべきです; 文書でどんな言語が使われていても必要とする文字を余裕を持って扱えます。加えて、常にできるだけ早く、HTML の {{HTMLElement("head")}} ブロック (先頭の 1 キロバイト内) に文字セットを特定するべきです、かなり <a href="http://support.microsoft.com/kb/928847">不快な Internet Explorer のセキュリティ脆弱性</a> から守ってくれるからです。</p>
+
+<h3 id="Viewport_meta_tag" name="Viewport_meta_tag">ビューポートメタタグ</h3>
+
+<p>最後に、HTML {{HTMLElement("head")}} にはビューポートメタタグを追加しなければなりません、例を示してモバイル端末でより良く動作するきっかけとなります。文書に少なくとも以下の内容を含めておき、必要になったら後ほど変更できます:</p>
+
+<pre class="brush: html example-good notranslate">&lt;meta name="viewport" content="width=device-width"&gt;</pre>
+
+<p>より詳しくは <a href="/ja/docs/Mobile/Viewport_meta_tag">モバイルブラウザーでのレイアウトを制御するために meta タグの viewport を使う</a> をご覧ください。</p>
+
+<h2 id="General_markup_coding_style" name="General_markup_coding_style">一般的なマークアップコーディングスタイル</h2>
+
+<h3 id="Use_lowercase" name="Use_lowercase">小文字を使う</h3>
+
+<p>すべての要素の名前と属性の名前/値に小文字を使ってください、綺麗に見えますし、マークアップをより早く書くことができます。</p>
+
+<p>良い例:</p>
+
+<pre class="brush: html example-good notranslate">&lt;p class="nice"&gt;This looks nice and neat&lt;/p&gt;</pre>
+
+<p>良くない例:</p>
+
+<pre class="brush: html example-bad notranslate">&lt;P CLASS="WHOA-THERE"&gt;Why is my markup shouting?&lt;/P&gt;</pre>
+
+<h3 id="Trailing_slashes" name="Trailing_slashes">末尾のスラッシュ</h3>
+
+<p>空要素に XHTML スタイルの末尾のスラッシュを含めないでください、不要ですし実行速度を遅くします。注意しないと古いブラウザーを中断させます (思い返してみると、Netscape 4 から問題とはなっていませんが)。</p>
+
+<p>こちらは良い例:</p>
+
+<pre class="brush: html example-good notranslate">&lt;input type="text"&gt;
+&lt;hr&gt;</pre>
+
+<p>スラッシュは必要ありません:</p>
+
+<pre class="brush: html example-bad notranslate">&lt;input type="text" /&gt;
+&lt;hr /&gt;</pre>
+
+<h3 id="Quoting_attributes" name="Quoting_attributes">属性を引用符で囲む</h3>
+
+<p>すべての属性の値はダブルクォートで囲わなければなりません。HTML5 でクオートの省略が許されるようになり、広まっていますが、取り入れるとマークアップが綺麗になり読みやすくなります。例えば、こちらは良い例です:</p>
+
+<pre class="brush: html example-good notranslate">&lt;img src="images/logo.jpg" alt="A circular globe icon" class="no-border"&gt;</pre>
+
+<p>次の例と比べてください。</p>
+
+<pre class="brush: html example-bad notranslate">&lt;img src=images/logo.jpg alt=A circular globe icon class=no-border&gt;</pre>
+
+<p>こちらは問題も引き起こします — 上記の例では <code>alt</code> 属性の部分が複数の属性と解釈されて実行が中断するでしょう、"A circular globe icon" が 1 つの属性の値であると特定するクォートがないためです。</p>
+
+<h3 id="Use_double_quotes" name="Use_double_quotes">ダブルクォートを使う</h3>
+
+<p>HTML にはシングルクォートでなく、ダブルクォートを使います:</p>
+
+<pre class="brush: html example-good notranslate">&lt;p class="important"&gt;Yes&lt;/p&gt;</pre>
+
+<pre class="brush: html example-bad notranslate">&lt;p class='important'&gt;Nope&lt;/p&gt;</pre>
+
+<h3 id="Boolean_attributes" name="Boolean_attributes">真偽属性</h3>
+
+<p>真偽属性は完全な形で書かないでください; 設定するには属性の名前だけ書きます。例えば、このように書きます:</p>
+
+<pre class="brush: html example-good notranslate">required</pre>
+
+<p>これだけで完全に理解され、うまく動作します。値を含めて書く長い形式、</p>
+
+<pre class="brush: html example-bad notranslate">required="required" </pre>
+
+<p>もサポートされるものの必須ではありません。</p>
+
+<h3 id="Class_and_ID_names" name="Class_and_ID_names">クラス名と ID 名</h3>
+
+<p>意味のあるクラス/ID 名を使い、複数の単語はハイフンで分割します。キャメルケース (camelCase) は使いません。</p>
+
+<p>良い:</p>
+
+<pre class="brush: html example-good notranslate">&lt;p class="editorial-summary"&gt;Blah blah blah&lt;/p&gt;</pre>
+
+<p>悪い:</p>
+
+<pre class="brush: html example-bad notranslate">&lt;p class="bigRedBox"&gt;Blah blah blah&lt;/p&gt;</pre>
+
+<h3 id="Entity_references" name="Entity_references">実体参照</h3>
+
+<p>実体参照を必要以上に使わない — リテラル文字を可能であれば使いましょう (角括弧や引用符のような記号は、まだエスケープが必要です) 。</p>
+
+<p>単純に書ける例</p>
+
+<pre class="brush: html example-good notranslate">&lt;p&gt;© 2018 Me&lt;/p&gt;</pre>
+
+<p>以下のようにも書けますが、</p>
+
+<pre class="brush: html example-bad notranslate">&lt;p&gt;&amp;copy; 2018 Me&lt;/p&gt;</pre>
+
+<p>UTF-8 文字セットで記述する限りは問題ありません。</p>
+
+<h2 id="Good_HTML_examples_on_MDN" name="Good_HTML_examples_on_MDN">MDN での良い HTML の例</h2>
+
+<p>優良で、簡潔で、有意義な HTML のスニペットを <a href="/ja/docs/Web/HTML/Reference">HTML リファレンス</a> の先頭で見つけることができます — 対話形式の例は一般的にこれらのガイドラインに従って書かれていますが、ガイドラインが新規に書かれる前に大部分が書かれているので、いくつかの箇所は異なっているのに気をつけてください。</p>
diff --git a/files/ja/mdn/guidelines/code_guidelines/index.html b/files/ja/mdn/guidelines/code_guidelines/index.html
new file mode 100644
index 0000000000..3ce931004f
--- /dev/null
+++ b/files/ja/mdn/guidelines/code_guidelines/index.html
@@ -0,0 +1,80 @@
+---
+title: Code example guidelines
+slug: MDN/Guidelines/Code_guidelines
+tags:
+  - CSS
+  - Code
+  - Guide
+  - Guidelines
+  - HTML
+  - JavaScript
+  - MDN Meta
+  - NeedsTranslation
+  - Shell
+  - TopicStub
+translation_of: MDN/Guidelines/Code_guidelines
+---
+<div>{{MDNSidebar}}</div>
+
+<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div>
+
+<div>
+<p class="summary"><span class="seoSummary">This document series outlines the coding guidelines and best practices we use for writing demos, code snippets, interactive examples, etc, for use on MDN.</span></p>
+
+<p>If you are looking for guidelines to follow when writing your code examples, you have come to the right place. The biggest advantage to adhering to these guidelines is that it will foster consistency across our samples and demos on MDN, which increases readability and comprehension overall.</p>
+</div>
+
+<div class="note">
+<p><strong>Note</strong>: If you want advice on the styling of code as it appears on an MDN article, rather than the code content, see our <a href="/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide#Code_sample_style_and_formatting">Writing style guide</a>.</p>
+</div>
+
+<h2 id="Article_structure">Article structure</h2>
+
+<p>This article contains general high-level best practices for writing MDN code examples. Its subarticles are as follows:</p>
+
+<ul>
+ <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General">General guidelines for all code</a> — both syntactical and for styling/displaying examples</li>
+ <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML">HTML guidelines</a></li>
+ <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS">CSS guidelines</a></li>
+ <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript">JavaScript guidelines</a></li>
+ <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell">Shell prompt guidelines</a></li>
+</ul>
+
+<h2 id="General_best_practices">General best practices</h2>
+
+<p>This section provides quick general best practices for creating an understandable minimal code sample to demonstrate usage of a specific feature or function.</p>
+
+<p>Code samples need to be:</p>
+
+<ul>
+ <li>simple enough to be understandable, but</li>
+ <li>complex enough to do something interesting, and preferably useful.</li>
+</ul>
+
+<p>There is one overarching consideration that you need to keep in mind: <strong>Readers will copy and paste the code sample into their own code, and may put it into production.</strong></p>
+
+<p>Therefore, you need to make sure that the code example is usable and follows generally accepted best practices, and <strong>does not</strong> do anything that will cause an application to be insecure, grossly inefficient, bloated, or inaccessible. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text — if it is a snippet and not a full example, make this clear. This also means that you should provide <strong>all</strong> of the information necessary to run the example including any dependencies and setup.</p>
+
+<p><span class="author-g-frc9o9ihh5c9qyd0">Code samples should be as self-contained and easy to understand as possible. The aim is not necessarily to produce efficient, clever code that impresses experts and has great functionality, but rather to produce reduced working examples that can be understood as quickly as possible.</span></p>
+
+<ul>
+</ul>
+
+<div id="magicdomid13"><span class="author-g-frc9o9ihh5c9qyd0">Guidelines:</span></div>
+
+<div id="magicdomid14"> </div>
+
+<div id="magicdomid15">
+<ul>
+ <li><span class="author-g-frc9o9ihh5c9qyd0">The sample should be short and ideally only show the feature you are immediately interested in.</span></li>
+ <li><span class="author-g-frc9o9ihh5c9qyd0"><strong>Only</strong> include code that is essential for the example. A large amount of non-relevant code can easily distract or confuse the audience. If you want to provide a full, more lengthy, example put it in one of our <a href="https://github.com/mdn/">Github repos</a> (or a JSBin, Codepen, or similar) and then provide the link to the full version above or below the sample.</span></li>
+ <li><span class="author-g-frc9o9ihh5c9qyd0">Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies — they make the code less portable, and harder to run and understand. Use vanilla code where possible.</span></li>
+ <li><span class="author-g-frc9o9ihh5c9qyd0">Don't assume knowledge of any libraries, frameworks, preprocessors, or other non-native features. For example, use class names that make sense within the example rather than classnames that make sense to BEM or Bootstrap users.</span></li>
+ <li><span class="author-g-frc9o9ihh5c9qyd0">Write your code as cleanly and understandably as possible, even if it is not the most efficient way to do it.</span></li>
+ <li><span class="author-g-frc9o9ihh5c9qyd0">Don't use bad practices for brevity (such as presentational elements like {{HTMLElement("big")}} or {{domxref("Document.write", "document.write()")}}); do it correctly.</span></li>
+ <li><span class="author-g-frc9o9ihh5c9qyd0">In the case of API demos, if you are using multiple APIs together point out what APIs are included, and what features come from where.</span></li>
+</ul>
+</div>
+
+<ul>
+</ul>