Hướng dẫn văn phong

Tuân theo hướng dẫn về kiểu TypeScript của Google.

Di chuyển sang TypeScript và ES6

Ban đầu, Blockly được viết bằng ES5.1 tuân thủ phiên bản cũ hơn, sau đó là phiên bản hiện tại của hướng dẫn về phong cách JavaScript của Google. Mã mới viết 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 như let, const, class, gán cấu trúc phân ly khi thích hợp. 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 ta sử dụng eslint và thiết lập tệp eslint.config.mjs với các quy tắc cho kiểu chúng ta ưu tiên.
  • Chúng ta sử dụng prettier để định dạng tự động.
  • Chạy npm run lint để chạy trình tìm lỗi mã nguồn và npm run format để chạy trình định dạng.
• Dùng dấu cách để thụt lề, chứ không phải dấu 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 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 ngoặc đơn (ngoại 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, bạn có nguy cơ sau khi tái cấu trúc ở cấp cao hơn trong hàm, biến sẽ bị bỏ lại và trở thành biến toàn cục bất ngờ.
• Bắt đầu chú thích bằng chữ in hoa và kết thúc bằng dấu chấm.
• Tạo các 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ã trước đây 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 lớ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 có định dạng không chính xác.
  • TSDoc của chúng tôi được tự động xuất bản trong tài liệu.
• 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 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.

Chú thích 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 bị bỏ qua khỏi 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 chú thích loại theo tài liệu về Trình biên dịch Closure.

Chế độ hiển thị

Bạn phải 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. Việc này sẽ 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 trực tiếp các biến thể chế độ hiển thị khác vào mã TypeScript, chứ không phải trong TSDoc.

Thuộc tính

TSDoc cho các thuộc tính phải bao gồm nội dung mô tả thuộc tính. Bạn có thể bỏ qua phần 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ả 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ề.

Bạn có thể bỏ qua nội dung mô tả cho các hàm, tham số hoặc giá trị trả về nếu nội dung đó tự giải thích được.

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