Hướng dẫn tạo kiểu khối

Làm theo hướng dẫn về kiểu Google TypeScript.

Di chuyển sang TypeScript và ES6

Blockly ban đầu được viết bằng ES5.1 theo phiên bản cũ hơn và hiện hành vào thời điểm đó trong hướng dẫn kiểu JavaScript của Google. Mã mới viết phải tuân thủ hướng dẫn quy định kiểu hiện tại và sử dụng các tính năng ngôn ngữ ES6 (như let, const, class), chỉ định cấu trúc (nếu có). Mã hiện tại có thể đã được cập nhật hoặc có thể không tuân thủ. Nhóm Blockly cố gắng đưa ra quyết định tốt nhất, có tính đến tính nhất quán của mã và trải nghiệm cho người dùng thư viện – ví dụ: chúng tôi có thể chọn không đổi tên các hàm công khai không còn tuân thủ hướng dẫn quy tắc.

Nên

• Sử dụng các công cụ tìm lỗi mã nguồn và định dạng.
  • Chúng ta sử dụng eslint và thiết lập một tệp .eslintrc.js với các quy tắc cho kiểu ưu tiên.
  • Chúng tôi sử dụng định dạng tự động đẹp hơn.
  • Chạy npm run lint để chạy linter và npm run format để chạy trình định dạng.
• Thụt lề theo dấu cách, chứ không phải theo tab.
• Sử dụng dấu chấm phẩy.
• Sử dụng camelCase cho các biến và hàm.
• Sử dụng TitleCase cho các lớp.
• Sử dụng ALL_CAPS cho các hằng số.
• Sử dụng dấu ngoặc nhọn cho tất cả các cấu trúc điều khiển.
  • Ngoại lệ: Bạn có thể bỏ qua dấu ngoặc nhọn đối với câu lệnh if một dòng.
• Dùng dấu nháy đơn (trừ phi viết JSON).
• Khai báo lại các biến trong vòng lặp for. Nghĩa là luôn viết for (const i = 0; ...) thay vì for (i = 0; ...).
  • Việc không làm như vậy sẽ làm tăng nguy cơ sau khi tái cấu trúc cao hơn trong hàm, biến sẽ bị mất nguồn gốc và trở thành biến toàn cầu bất ngờ.
• Bắt đầu nhận xét bằng chữ cái viết hoa và kết thúc nhận xét bằng dấu chấm.
• Tạo vấn đề GitHub với TODO và liên kết chúng bằng TODO(#issueNumber).
• Chú thích mọi thứ bằng TSDoc.

Không nên

• Thụt lề theo tab.
• Dùng dấu gạch dưới ở cuối tên biến hoặc hàm.
  • Một số mã trước đó sử dụng dấu gạch dưới cho các thuộc tính hoặc hàm riêng tư hoặc nội bộ. Mặc dù các tệp này có thể tiếp tục tồn tại, nhưng bạn không được thêm mã mới theo quy ước này.
• Sử dụng snake_case.
• Dùng dấu ngoặc kép (trừ khi viết JSON).
• Sử dụng TSDoc không đúng định dạng.
  • TSDoc của chúng tôi được tự động xuất bản trong tài liệu của chúng tôi.
• Viết TODO (username).
  • Thay vào đó, hãy tạo các vấn đề GitHub với TODO và liên kết chúng bằng TODO(#issueNumber).
• Sử dụng string.startsWith. Sử dụng Blockly.utils.string.startsWith thay thế.

Tài liệu hướng dẫn (TS)

Nhóm Blockly sử dụng TSDoc để chú thích mã của chúng tôi và tạo tài liệu. Chúng tôi dự kiến có TSDoc cho mọi thuộc tính công khai của các lớp và cho mọi hàm đã xuất.

Các nhận xét trong TSDoc phải bắt đầu bằng /** và kết thúc bằng */ để được phân tích cú pháp chính xác.

Loại

Các loại sẽ bị bỏ qua trong TSDoc vì thông tin đó nằm trực tiếp trong mã TypeScript. Nếu bạn đang chỉnh sửa một trong số ít tệp JavaScript còn lại, hãy thêm các chú thích kiểu theo tài liệu về Trình biên dịch đóng.

Chế độ hiển thị

Các hàm hoặc thuộc tính chỉ truy cập được trong thư viện Blockly phải được chú giải bằng @internal. Thao tác này ngăn các thuộc tính này xuất hiện trong tài liệu công khai. Bạn nên đặt các đối tượng sửa đổi chế độ hiển thị khác trực tiếp trong mã TypeScript, chứ không phải trong TSDoc.

Thuộc tính

Tài liệu hướng dẫn cho cơ sở lưu trú phải bao gồm nội dung mô tả về cơ sở lưu trú. Bạn có thể bỏ qua nội dung mô tả đối với các thuộc tính tự giải thích.

/**
  *   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);

Hàm

Chú thích cho hàm phải bao gồm

• Nội dung mô tả về hàm
• Một thẻ @param cho mỗi thông số, bao gồm cả
  • Tên
  • Nội dung mô tả
• Thẻ @returns nếu hàm sẽ trả về một giá trị, kèm theo nội dung mô tả về giá trị được trả về.

Có thể bỏ qua nội dung mô tả cho các hàm, tham số hoặc giá trị trả về nếu chúng dễ hiểu.

Ví dụ:

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