From da78a9e329e272dedb2400b79a3bdeebff387d47 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:42:17 -0500 Subject: initial commit --- .../code_guidelines/code_guidelines/index.html | 159 +++++++++++++ .../mdn/guidelines/code_guidelines/css/index.html | 249 +++++++++++++++++++++ files/ko/mdn/guidelines/code_guidelines/index.html | 80 +++++++ 3 files changed, 488 insertions(+) create mode 100644 files/ko/mdn/guidelines/code_guidelines/code_guidelines/index.html create mode 100644 files/ko/mdn/guidelines/code_guidelines/css/index.html create mode 100644 files/ko/mdn/guidelines/code_guidelines/index.html (limited to 'files/ko/mdn/guidelines/code_guidelines') 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 +--- +
{{MDNSidebar}}{{IncludeSubnav("/ko/docs/MDN")}}
+ +

아래 코드 예제 가이드라인에서 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 라인 정도의 길이가 이상적입니다. 코드 블럭이 너무 길어진다면, 가장 유용한 스니펫만 보여주고, 나머지 부분은 깃허브 저장소나 코드펜 같은 링크로 연결하세요.

+ +

예제 디스플레이 가이드라인

+ +

렌더링 된 예제 크기

+ +

MDN 메인 콘텐츠 창은 데스크탑에서 약  700px 크기 이므로, 삽입된 MDN 예제는 ( 삽입된 예제를 100% 너비로 설정했을 때 ) 해당 너비에서 잘 보여야 합니다.

+ +

높이의 경우, 최대한의 화면 가독성을 위해 가능하면 렌더링 된 예제 높이를 700px 아래로 유지하는 것을 추천합니다.

+ +

모바일 디바이스에서도 예제가 잘 보이도록 어느 정도는 반응형으로 동작되도록 예제를 작성하는데 신경써야 합니다.

+ +

이미지나 다른 미디어의 사용

+ +

가끔 이미지나 다른 미디어를 예제에 삽입하고 싶을 때가 있습니다. 그럴 때에는:

+ + + +

컬러의 사용

+ +

소문자 16진수 대신, 음영이나 주요 컬러(즉, 검은색, 흰색, 빨간색)는 키워드를 사용할 수있습니다. 필요한 경우에만 좀 더 복잡한 컬러스킴을 사용하세요.( 예를 들면, 투명색이 필요할 때)

+ +

주요 "기본" 컬러는 키워드로 설정하는것이 좋습니다. 예를 들면:

+ +
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 가이드라인(프론트엔드 코드베이스용)은 전체 MDN 디자인에 사용된 유용한 컬러셋을 포함하고 있습니다. ( 역자주: 영어 원문 링크가 깨져 MDN Fiori 깃허브 리포 에서 비슷한 링크를 찾아 연결했습니다.)

+ +

좋은 예시와 나쁜 예시 강조

+ +

이 가이드라인에서 알 수 있는 것처럼, 좋은 실습예시는 연두색에 웃는얼굴로 강조되며, 나쁜 실습 예시는 슬픈표정에 빨간 바탕으로 강조됩니다.

+ +

이 처럼 하려면, MDN 에디터 콘트롤로 코드 블럭을 <pre> 블럭이 되도록 하고, 적절한 문법 강조를 설정해야 합니다. 소스 코드는 아래와 비슷하게 보일겁니다:

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

이 상태에서 좋은 예시로 만들려면, class 속성의 오른쪽 따옴표 바로 앞에 example-good을 넣으면 됩니다:

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

나쁜 예시로 만들려면, class 속성의 오른쪽 따옴표 바로 앞에 example-bad를 넣으면 됩니다:

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

우리는 당신이 이 기능을 사용하길 권장합니다. 모든 곳에 사용할 필요는 없습니다. 당신의 코드에서 좋은 예와 나쁜 예를 구분할 필요가 있을때 사용하세요.

+ +

레퍼런스 페이지에서 문법 섹션 작성

+ +

MDN 레퍼런스 페이지에는  JavaScript 메서드, CSS 속성, HTML 요소 등과 같이 기능의 구문이 무엇을 할 수 있고, 어때야 하는지 명확하게 보여주는 문법 섹션(Syntax section)이 포함되어 있습니다. 이 내용을 작성하는 가이드라인은 Syntax sections 문서를 참고하세요.

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 +--- +
{{MDNSidebar}}{{IncludeSubnav("/en-US/docs/MDN")}}
+ +

다음 가이드라인은 MDN code 예제를 위한 CSS 작성 방법을 설명합니다.

+ +

이번 기사에서는

+ + + +

High-level guidelines

+ +

Don't use preprocessors

+ +

Don't use preprocessor syntax, e.g. Sass, Less, or Stylus, 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.

+ +

Don't use specific CSS methodologies

+ +

In the same spirit as the previous guideline, don't write MDN example code using a specific CSS methodology such as BEM or SMACSS. Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies.

+ +

Use flexible/relative units

+ +

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 Responsive design building blocks article.

+ +

Don't use resets

+ +

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.

+ +

If you really feel like you need to use a reset, consider using normalize.css by Nicolas Gallagher, which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on <body>, for example) and fix a few bugs.

+ +

Plan your CSS — avoid overriding

+ +

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.

+ +

General CSS coding style

+ +

Use expanded syntax

+ +

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.

+ +

Use this:

+ +
p {
+  color: white;
+  background-color: black;
+  padding: 1rem;
+}
+ +

Not this:

+ +
p { color: white; background-color: black; padding: 1rem; }
+ +

In addition, keep these specifics in mind:

+ + + +

Favor longhand rules over terse shorthand

+ +

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.

+ +

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:

+ +
font: small-caps bold 2rem/1.5 sans-serif;
+ +

Whereas this is more immediate in terms of understanding:

+ +
font-variant: small-caps;
+font-weight: bold;
+font-size: 2rem;
+line-height: 1.5;
+font-family: sans-serif;
+ +

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:

+ + + +

In addition, some shorthands only work as expected if you include the different value components in a certain order. In CSS animations for example:

+ +
/* duration | timing-function | delay | iteration-count
+   direction | fill-mode | play-state | name */
+animation: 3s ease-in 1s 2 reverse both paused slidein;
+ +

As an example, the first value that can be parsed as a <time> is assigned to the animation-duration, and the second one is assigned to animation-delay. For more details, read the full animation syntax details.

+ +

Use double quotes around values

+ +

Where quotes can or should be included, use them, and use double quotes. For example:

+ +
[data-vegetable="liquid"] {
+  background-color: goldenrod;
+  background-image: url("../../media/examples/lizard.png");
+}
+ +

Spacing around function parameters

+ +

Function parameters should have spaces after their separating commas, but not before:

+ +
color: rgb(255, 0, 0);
+background-image: linear-gradient(to bottom, red, black);
+ +

CSS comments

+ +

Use CSS-style comments to comment code that isn't self-documenting:

+ +
/* This is a CSS-style comment */
+ +

Put your comments on separate lines preceeding the code they are referring to:

+ +
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;
+}
+ +

Also note that you should leave a space between the asterisks and the comment, in each case.

+ +

Don't use !important

+ +

!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.

+ +

Bad:

+ +
.bad-code {
+  font-size: 4rem !important;
+}
+ +

Specific CSS syntax points

+ +

Turning off borders and other properties

+ +

When turning off borders (and any other properties that can take 0 or none as values), use 0 rather than none:

+ +
border: 0;
+ +

Use "mobile first" media queries

+ +

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.

+ +
/*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*/
+}
+ +

This has many advantages, outlined in our Mobile First article.

+ +

Selectors

+ +

Don't use ID selectors

+ +

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.

+ +

Good:

+ +
.editorial-summary {
+  ...
+}
+ +

Bad:

+ +
#editorial-summary {
+  ...
+}
+ +

Put multiple selectors on separate lines

+ +

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.

+ +

Do this:

+ +
h1,
+h2,
+h3 {
+  font-family: sans-serif;
+  text-align: center;
+}
+ +

Not this:

+ +
h1, h2, h3 {
+  font-family: sans-serif;
+  text-align: center;
+}
+ +

Good CSS examples on MDN

+ +

You can find good, concise, meaningful CSS snippets at the top of our CSS property reference pages — browse through our CSS keyword index 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.

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 +--- +
{{MDNSidebar}}
+ +
{{IncludeSubnav("/en-US/docs/MDN")}}
+ +
+

This document series outlines the coding guidelines and best practices we use for writing demos, code snippets, interactive examples, etc, for use on MDN.

+ +

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.

+
+ +
+

Note: If you want advice on the styling of code as it appears on an MDN article, rather than the code content, see our Writing style guide.

+
+ +

Article structure

+ +

This article contains general high-level best practices for writing MDN code examples. Its subarticles are as follows:

+ + + +

General best practices

+ +

This section provides quick general best practices for creating an understandable minimal code sample to demonstrate usage of a specific feature or function.

+ +

Code samples need to be:

+ + + +

There is one overarching consideration that you need to keep in mind: Readers will copy and paste the code sample into their own code, and may put it into production.

+ +

Therefore, you need to make sure that the code example is usable and follows generally accepted best practices, and does not 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 all of the information necessary to run the example including any dependencies and setup.

+ +

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.

+ + + +
Guidelines:
+ +
 
+ +
+ +
+ + -- cgit v1.2.3-54-g00ecf