이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Blockly 스타일 가이드

TypeScript 및 ES6으로 이전

Blockly는 원래 이전 버전의 Google JavaScript 스타일 가이드에 따라 ES5.1로 작성되었습니다. 새로 작성된 코드는 현재 스타일 가이드를 준수해야 하며 let, const, class, 디스트럭처링 할당(해당하는 경우)과 같은 ES6 언어 기능을 사용해야 합니다. 기존 코드가 업데이트되거나 규정을 준수하지 않을 수 있습니다. Blockly팀은 코드 일관성과 라이브러리 사용자 환경을 고려하여 최선의 결정을 내리고자 합니다. 예를 들어, 더 이상 스타일 가이드를 준수하지 않는 공개 함수의 이름을 변경하지 않을 수 있습니다.

권장사항

린트 작업 및 서식 지정 도구를 사용합니다.
- eslint를 사용하며 원하는 스타일의 규칙으로 설정된 .eslintrc.js 파일을 가지고 있습니다.
- Google에서는 자동 서식을 사용할 때 더 보기 좋게 사용합니다.
- npm run lint를 실행하여 린터를 실행하고 npm run format를 실행하여 형식 지정 도구를 실행합니다.
들여쓰기는 탭이 아닌 공백으로 처리됩니다.
세미콜론을 사용합니다.
변수와 함수에 camelCase를 사용합니다.
클래스에 TitleCase를 사용합니다.
상수에는 ALL_CAPS를 사용합니다.
모든 컨트롤 구조에 중괄호를 사용합니다.
- 예외: 한 줄 if 문의 중괄호는 생략할 수 있습니다.
작은따옴표를 사용합니다 (JSON 작성 시 제외).
for 루프에서 변수를 다시 선언합니다. 즉, 항상 for (i = 0; ...) 대신 for (const i = 0; ...)를 작성합니다.
- 이렇게 하지 않으면 함수의 상위로 리팩터링한 후에 변수가 분리되어 깜짝 전역이 될 위험이 커집니다.
댓글은 대문자로 시작하고 마침표로 끝냅니다.
TODO와 함께 GitHub 문제를 만들고 TODO(#issueNumber)를 사용하여 연결합니다.
모든 항목에 TSDoc 주석을 답니다.

금지사항

탭을 사용하여 들여쓰기
변수 또는 함수 이름 끝에 밑줄을 사용합니다.
- 일부 이전 코드는 비공개 또는 내부 속성이나 함수에 밑줄을 사용합니다. 이러한 코드도 계속 존재할 수 있지만, 이 규칙에 따라 새로운 코드를 추가하면 안 됩니다.
snake_case를 사용합니다.
큰따옴표를 사용합니다 (JSON을 작성하는 경우 제외).
잘못된 형식의 TSDoc를 사용합니다.
- Google TSDoc는 문서의 일부로 자동 게시됩니다.
TODO (username)를 작성합니다.
- 대신 TODO로 GitHub 문제를 만들고 TODO(#issueNumber)을 사용하여 연결합니다.
string.startsWith를 사용합니다. 대신 Blockly.utils.string.startsWith를 사용합니다.

TS 문서

Blockly팀은 TSDoc를 사용하여 코드에 주석을 달고 문서를 생성합니다. 클래스의 모든 공개 속성 및 내보낸 모든 함수에 TSDoc가 필요할 것으로 예상됩니다.

TSDoc 주석은 /**로 시작하고 */로 끝나야 올바르게 파싱됩니다.

유형

유형은 TSDoc에서 생략됩니다. 이 정보는 TypeScript 코드에 직접 있기 때문입니다. 나머지 몇 가지 자바스크립트 파일 중 하나를 수정하는 경우 클로저 컴파일러 문서에 따라 유형 주석을 포함합니다.

공개 상태

Blockly 라이브러리 내에서만 액세스해야 하는 함수 또는 속성은 @internal로 주석 처리해야 합니다. 이렇게 하면 이러한 속성이 공개 문서에 표시되지 않습니다. 다른 공개 상태 수정자는 TSDoc이 아닌 TypeScript 코드에 직접 배치해야 합니다.

속성

속성 TSDoc에는 속성 설명이 포함되어야 합니다. 설명이 필요 없는 속성의 경우 설명이 생략될 수 있습니다.

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

함수

함수의 주석에는

함수 설명
매개변수당 @param 태그 1개(
- 이름
- 설명
함수가 반환된 값에 대한 설명과 함께 값을 반환하는 경우 @returns 태그

함수, 매개변수 또는 반환 값에 대해 설명이 필요 없는 경우 설명을 생략할 수 있습니다.

예를 들면 다음과 같습니다.

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}