diff options
Diffstat (limited to 'files/ko/mdn/guidelines/code_guidelines')
3 files changed, 488 insertions, 0 deletions
diff --git a/files/ko/mdn/guidelines/code_guidelines/code_guidelines/index.html b/files/ko/mdn/guidelines/code_guidelines/code_guidelines/index.html new file mode 100644 index 0000000000..093f50ae47 --- /dev/null +++ b/files/ko/mdn/guidelines/code_guidelines/code_guidelines/index.html @@ -0,0 +1,159 @@ +--- +title: 모든 코드에 대한 일반 가이드라인 +slug: MDN/Guidelines/Code_guidelines/Code_guidelines +tags: + - Code + - General + - Guide + - MDN Meta + - 가이드 + - 가이드라인 + - 코드 블럭 + - 코드 블록 + - 코드 스타일 +translation_of: MDN/Guidelines/Code_guidelines/General +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<p class="summary">아래 코드 예제 가이드라인에서 HTML, CSS, JavaScript 나 다른 어느 코드로 예로 들건 , 모든 코드 타입에 적용됩니다.</p> + +<h2 id="이_문서_내용은"> 이 문서 내용은</h2> + +<ul> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#들여쓰기_여백주기_사이즈">들여쓰기, 여백주기, 사이즈</a> + + <ul> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#들여쓰기">들여쓰기</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#코드_한_줄_길이">코드 한 줄 길이</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#코드_블럭_높이">코드 블럭 높이</a></li> + </ul> + </li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#예제_디스플레이_가이드라인">예제 디스플레이 가이드라인</a> + <ul> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#렌더링_된_예제_크기">렌더링 된 예제 크기</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#이미지나_다른_미디어의_사용">이미지나 다른 미디어의 사용</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#컬러의_사용">컬러의 사용</a></li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#좋은_예시와_나쁜_예시_강조">좋은 예시와 나쁜 예시 강조</a></li> + </ul> + </li> + <li><a href="/ko/docs/MDN/Contribute/Guidelines/Code_guidelines/General#레퍼런스_페이지에서_문법_섹션_작성">레퍼런스 페이지에 문법 섹션 작성</a></li> +</ul> + +<h2 id="들여쓰기_여백주기_사이즈">들여쓰기, 여백주기, 사이즈</h2> + +<h3 id="들여쓰기">들여쓰기</h3> + +<p>모든 코드는 2 스페이스로 들여쓰기 해야합니다. 예를 들면:</p> + +<pre class="brush: html example-good notranslate"><div> + <p>This is my paragraph.</p> +</div></pre> + +<pre class="brush: js example-good notranslate">function myFunc() { + if(thingy) { + console.log('Yup, that worked.'); + } +}</pre> + +<h3 id="코드_한_줄_길이">코드 한 줄 길이</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="코드_블럭_높이">코드 블럭 높이</h3> + +<p>코드 블럭은 필요한 만큼 길어야 하지만 너무 길면 안됩니다. 15에서 25 라인 정도의 길이가 이상적입니다. 코드 블럭이 너무 길어진다면, 가장 유용한 스니펫만 보여주고, 나머지 부분은 깃허브 저장소나 코드펜 같은 링크로 연결하세요.</p> + +<h2 id="예제_디스플레이_가이드라인">예제 디스플레이 가이드라인</h2> + +<h3 id="렌더링_된_예제_크기">렌더링 된 예제 크기</h3> + +<p>MDN 메인 콘텐츠 창은 데스크탑에서 약 700px 크기 이므로, 삽입된 MDN 예제는 ( 삽입된 예제를 100% 너비로 설정했을 때 ) 해당 너비에서 잘 보여야 합니다.</p> + +<p>높이의 경우, 최대한의 화면 가독성을 위해 가능하면 렌더링 된 예제 높이를 700px 아래로 유지하는 것을 추천합니다.</p> + +<p>모바일 디바이스에서도 예제가 잘 보이도록 어느 정도는 반응형으로 동작되도록 예제를 작성하는데 신경써야 합니다.</p> + +<h3 id="이미지나_다른_미디어의_사용">이미지나 다른 미디어의 사용</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/">Creative Commons Attribution-ShareAlike license</a> (CC-BY-SA) 중 하나를 사용하도록 해야합니다.</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="컬러의_사용">컬러의 사용</h3> + +<p>소문자 16진수 대신, 음영이나 주요 컬러(즉, 검은색, 흰색, 빨간색)는 키워드를 사용할 수있습니다. 필요한 경우에만 좀 더 복잡한 컬러스킴을 사용하세요.( 예를 들면, 투명색이 필요할 때)</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-fiori.netlify.app/">MDN's Fiori 가이드라인</a>(프론트엔드 코드베이스용)은 전체 MDN 디자인에 사용된 <a href="https://mdn-fiori.netlify.app/?path=/docs/docs-colors--page">유용한 컬러셋</a>을 포함하고 있습니다. ( 역자주: 영어 원문 링크가 깨져 <a href="https://github.com/mdn/mdn-fiori">MDN Fiori 깃허브 리포</a> 에서 비슷한 링크를 찾아 연결했습니다.)</p> + +<h3 id="좋은_예시와_나쁜_예시_강조">좋은 예시와 나쁜 예시 강조</h3> + +<p>이 가이드라인에서 알 수 있는 것처럼, 좋은 실습예시는 연두색에 웃는얼굴로 강조되며, 나쁜 실습 예시는 슬픈표정에 빨간 바탕으로 강조됩니다.</p> + +<p>이 처럼 하려면, MDN 에디터 콘트롤로 코드 블럭을 <code><pre></code> 블럭이 되도록 하고, 적절한 문법 강조를 설정해야 합니다. 소스 코드는 아래와 비슷하게 보일겁니다:</p> + +<pre class="notranslate"><pre class="brush: js"> +function myFunc() { + console.log('Hello!'); +};</pre></pre> + +<p>이 상태에서 좋은 예시로 만들려면, <code>class</code> 속성의 오른쪽 따옴표 바로 앞에 <code>example-good</code>을 넣으면 됩니다:</p> + +<pre class="notranslate"><pre class="brush: js example-good"> + ...</pre> + +<p>나쁜 예시로 만들려면, <code>class</code> 속성의 오른쪽 따옴표 바로 앞에 <code>example-bad</code>를 넣으면 됩니다:</p> + +<pre class="notranslate"><pre class="brush: js example-bad"> + ...</pre> + +<p>우리는 당신이 이 기능을 사용하길 권장합니다. 모든 곳에 사용할 필요는 없습니다. 당신의 코드에서 좋은 예와 나쁜 예를 구분할 필요가 있을때 사용하세요.</p> + +<h2 id="레퍼런스_페이지에서_문법_섹션_작성">레퍼런스 페이지에서 문법 섹션 작성</h2> + +<p>MDN 레퍼런스 페이지에는 JavaScript 메서드, CSS 속성, HTML 요소 등과 같이 기능의 구문이 무엇을 할 수 있고, 어때야 하는지 명확하게 보여주는 문법 섹션(Syntax section)이 포함되어 있습니다. 이 내용을 작성하는 가이드라인은 <a href="/ko/docs/MDN/Contribute/Structures/Syntax_sections">Syntax sections</a> 문서를 참고하세요.</p> diff --git a/files/ko/mdn/guidelines/code_guidelines/css/index.html b/files/ko/mdn/guidelines/code_guidelines/css/index.html new file mode 100644 index 0000000000..cbcbd11ae8 --- /dev/null +++ b/files/ko/mdn/guidelines/code_guidelines/css/index.html @@ -0,0 +1,249 @@ +--- +title: CSS 가이드라인 +slug: MDN/Guidelines/Code_guidelines/CSS +translation_of: MDN/Guidelines/Code_guidelines/CSS +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">다음 가이드라인은 MDN code 예제를 위한 CSS 작성 방법을 설명합니다.</p> + +<h2 id="이번_기사에서는">이번 기사에서는</h2> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#High-level_guidelines">고급 가이드라인</a> + + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_preprocessors">전처리기를 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_specific_CSS_methodologies">특정 CSS 방법론을 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_flexiblerelative_units">유연하고/상대적인 단위를 사용합니다</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_resets">재설정을 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Plan_your_CSS_%E2%80%94_avoid_overriding">CSS 계획 — 재정의 (overriding) 를 방지합니다</a></li> + </ul> + </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#General_CSS_coding_style">일반적인 CSS 코딩 스타일</a> + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_expanded_syntax">확장 구문을 사용합니다</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Favor_longhand_rules_over_terse_shorthand">속기 (shorthand) 보다는 longhand 규칙을 좋아합니다</a> </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_double_quotes_around_values">값을 큰 따옴표로 묶습니다</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Spacing_around_function_parameters">함수 매개변수 주위의 간격</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#CSS_comments">CSS 주석</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_!important">!important 를 사용하지 마십시오</a></li> + </ul> + </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Specific_CSS_syntax_points">특정 CSS 구문 포인트</a> + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Turning_off_borders_and_other_properties">테두리 및 기타 속성 끄기</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Use_mobile_first_media_queries">"모바일 우선" 미디어 쿼리 사용</a></li> + </ul> + </li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Selectors">선택자</a> + <ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Dont_use_ID_selectors">ID 선택자를 사용하지 마십시오</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS#Put_multiple_selectors_on_separate_lines">여러 라인을 별도의 라인에 배치</a></li> + </ul> + </li> +</ul> + +<h2 id="High-level_guidelines">High-level guidelines</h2> + +<h3 id="Dont_use_preprocessors">Don't use preprocessors</h3> + +<p>Don't use preprocessor syntax, e.g. <a href="https://sass-lang.com/">Sass</a>, <a href="http://lesscss.org/">Less</a>, or <a href="http://stylus-lang.com/">Stylus,</a> in your MDN example code. MDN documents the vanilla CSS language, and using preprocessors only serves to raise the bar to understanding the examples, potentially confusing readers.</p> + +<h3 id="Dont_use_specific_CSS_methodologies">Don't use specific CSS methodologies</h3> + +<p>In the same spirit as the previous guideline, don't write MDN example code using a specific CSS methodology such as <a href="http://getbem.com/naming/">BEM</a> or <a href="https://smacss.com/">SMACSS</a>. Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies.</p> + +<h3 id="Use_flexiblerelative_units">Use flexible/relative units</h3> + +<p>For maximum flexibility over the widest possible range of devices, it is a good idea to size containers, padding, etc. using relative units like ems and rems, or percentages and viewport units if you want them to vary depending on viewport width. You can read some more about this in our <a href="/en-US/docs/Web/Apps/app_layout/responsive_design_building_blocks#Fluid_grids">Responsive design building blocks</a> article.</p> + +<h3 id="Dont_use_resets">Don't 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><body></code>, for example) and fix a few bugs.</p> + +<h3 id="Plan_your_CSS_—_avoid_overriding">Plan your CSS — avoid overriding</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">General CSS coding style</h2> + +<h3 id="Use_expanded_syntax">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">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 <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/time" title="The <time> CSS data type represents a time value expressed in seconds or milliseconds. It is used in animation, transition, and related properties."><code><time></code></a> is assigned to the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/animation-duration" title="The animation-duration CSS property sets the length of time that an animation takes to complete one cycle."><code>animation-duration</code></a>, and the second one is assigned to <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/animation-delay" title="The animation-delay CSS property sets when an animation starts. The animation can start later, immediately from its beginning, or immediately and partway through the animation."><code>animation-delay</code></a>. 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">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">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_comments">CSS comments</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">Don't use !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">Specific CSS syntax points</h2> + +<h3 id="Turning_off_borders_and_other_properties">Turning off borders and other properties</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">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">Selectors</h2> + +<h3 id="Dont_use_ID_selectors">Don't use ID selectors</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">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">Good CSS examples on MDN</h2> + +<p>You can find good, concise, meaningful CSS snippets at the top of our CSS property reference pages — browse through our <a href="/en-US/docs/Web/CSS/Reference#Keyword_index">CSS keyword index</a> to find some. Our interactive examples are generally written to follow the above guidelines, although be aware that they may differ in some places as they were mostly written before the guidelines were newly written.</p> diff --git a/files/ko/mdn/guidelines/code_guidelines/index.html b/files/ko/mdn/guidelines/code_guidelines/index.html new file mode 100644 index 0000000000..3ce931004f --- /dev/null +++ b/files/ko/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> |