Blockly 스타일 가이드

Google TypeScript 스타일 가이드를 따릅니다.

TypeScript 및 ES6로 이전

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

권장사항

  • 린팅 및 형식 지정 도구를 사용합니다.
    • eslint를 사용하며 선호하는 스타일의 규칙이 설정된 .eslintrc.js 파일이 있습니다.
    • 자동 형식 지정에는 prettier가 사용됩니다.
    • 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을 사용하세요.
    • TSDoc은 문서의 일부로 자동 게시됩니다.
  • TODO (username)를 작성합니다.
    • 대신 TODO가 있는 GitHub 문제를 만들고 TODO(#issueNumber)를 사용하여 연결합니다.
  • string.startsWith을 사용합니다. 대신 Blockly.utils.string.startsWith를 사용합니다.

TSDoc

Blockly팀은 TSDoc을 사용하여 코드에 주석을 달고 문서를 생성합니다. 클래스의 모든 공개 속성과 모든 내보낸 함수에 TSDoc이 있어야 합니다.

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

유형

정보가 TypeScript 코드에 있으므로 TSDoc에서 유형이 생략됨 할 수 있습니다. 남아 있는 몇 안 되는 JavaScript 파일 중 하나를 수정하는 경우 Closure 컴파일러 문서에 따라 유형 주석을 포함합니다.

공개 상태

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개, 다음을 포함: <ph type="x-smartling-placeholder">
      </ph>
    • 이름
    • 설명
  • 함수가@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;
}