스타일 가이드

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

TypeScript 및 ES6로의 이전

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

권장사항

  • 린팅 및 형식 지정 도구를 사용합니다.
    • eslint를 사용하며 선호하는 스타일에 관한 규칙이 설정된 eslint.config.mjs 파일이 있습니다.
    • 자동 형식을 지정하는 데 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 태그(
      포함)
    • 이름
    • 설명
  • 함수가 값을 반환하는 경우 반환된 값에 관한 설명과 함께 @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;
}