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

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

Di chuyển sang TypeScript và ES6

Blockly ban đầu được viết bằng phiên bản ES5.1 tuân theo một phiên bản cũ, phiên bản hiện tại của kiểu Google JavaScript hướng dẫn. Mới viết mã phải tuân thủ hướng dẫn quy tắc hiện tại và sử dụng các tính năng ngôn ngữ ES6 chẳng hạn như let, const, class, huỷ cấu trúc nội dung chỉ định (nếu có). Mã hiện có có thể được cập nhật hoặc 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 về kiểu.

Nên

• Sử dụng công cụ tìm lỗi mã nguồn và định dạng.
  • Chúng tôi dùng eslint và có một .eslintrc.js thiết lập tệp với các quy tắc cho kiểu mà chúng tôi ưu tiên.
  • Chúng ta sử dụng prettier để định dạng tự động.
  • Chạy npm run lint để chạy linter và npm run format để chạy trình định dạng.
• Thụt lề bằng dấu cách, chứ không phải thẻ.
• 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 học.
• Sử dụng ALL_CAPS cho hằng số.
• Sử dụng dấu ngoặc nhọn cho tất cả cấu trúc điều khiển.
  • Ngoại lệ: Bạn có thể bỏ qua dấu ngoặc nhọn cho câu lệnh if một dòng.
• Sử dụng dấu nháy đơn (trừ khi 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; ...).
  • Nếu không làm như vậy, thì nguy cơ sau khi được tái cấu trúc ở mức cao hơn trong thì biến sẽ bị mất nguồn gốc và trở thành một hàm toàn cục bất ngờ.
• Bắt đầu nhận xét bằng chữ in hoa và kết thúc bằng dấu chấm.
• Tạo vấn đề trên GitHub bằng TODO và liên kết các vấn đề đó bằng TODO(#issueNumber).
• Chú giải mọi thứ bằng TSDoc.

Không nên

• Dùng thẻ để thụt lề.
• Sử dụng dấu gạch dưới ở cuối tên biến hoặc hàm.
  • Một số mã cũ sử dụng dấu gạch dưới cho thuộc tính riêng tư hoặc nội bộ hoặc . 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.
• Sử dụng dấu ngoặc kép (ngoại 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 đề trên GitHub bằng TODO và liên kết các vấn đề đó bằng cách sử dụng TODO(#issueNumber).
• Sử dụng string.startsWith. Thay vào đó, hãy sử dụng Blockly.utils.string.startsWith.

TSDoc

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

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

Loại

Các loại bị bỏ qua khỏi TSDoc vì thông tin đó nằm trong mã TypeScript trực tiếp. 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 chú thích loại theo tài liệu về Trình biên dịch Closure.

Chế độ hiển thị

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

Thuộc tính

TSDoc cho thuộc tính phải bao gồm nội dung mô tả về thuộc tính. Bạn có thể bỏ qua phần mô tả cho 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 tham số, bao gồm cả
  • Tên
  • Mô tả
• Thẻ @returns nếu hàm sẽ trả về một giá trị, kèm theo nội dung mô tả 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 là 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;
}