1. Giới thiệu
Tài liệu này đóng vai trò là định nghĩa đầy đủ về các tiêu chuẩn mã hóa Google Google cho mã nguồn trong ngôn ngữ lập trình JavaScript. Một tệp nguồn JavaScript được mô tả là theo kiểu Google khi và chỉ khi nó tuân thủ các quy tắc trong tài liệu này.complete definition of Google’s coding standards for source code in the JavaScript programming language. A JavaScript source file is described as being in Google Style if and only if it adheres to the rules herein.
Giống như các hướng dẫn phong cách lập trình khác, các vấn đề bao gồm khoảng thời gian không chỉ các vấn đề thẩm mỹ của định dạng, mà cả các loại quy ước hoặc tiêu chuẩn mã hóa khác. Tuy nhiên, tài liệu này tập trung chủ yếu vào các quy tắc khó và nhanh mà chúng tôi tuân theo phổ biến và tránh đưa ra lời khuyên không thể thực thi rõ ràng [dù là con người hay công cụ].
1.1 Ghi chú thuật ngữ
Trong tài liệu này, trừ khi có được làm rõ khác:
Thuật ngữ bình luận luôn đề cập đến ý kiến thực hiện. Chúng tôi không sử dụng các nhận xét tài liệu cụm từ, thay vào đó sử dụng thuật ngữ phổ biến là JSDOC, cho cả hai chú thích văn bản và có thể đọc được bằng máy trong
48./* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
Hướng dẫn kiểu này sử dụng thuật ngữ RFC 2119 khi sử dụng các cụm từ phải, không nên, không nên, và có thể. Các thuật ngữ thích và tránh tương ứng với nên và không nên, tương ứng. Các tuyên bố bắt buộc và khai báo là quy định và tương ứng với phải.
Các ghi chú thuật ngữ khác sẽ thỉnh thoảng xuất hiện trong suốt tài liệu.
1.2 Ghi chú hướng dẫn
Mã ví dụ trong tài liệu này là không quy phạm. Đó là, trong khi các ví dụ theo kiểu Google, chúng có thể không minh họa cách duy nhất phong cách để đại diện cho mã. Các lựa chọn định dạng tùy chọn được thực hiện trong các ví dụ không được thực thi như các quy tắc.non-normative. That is, while the examples are in Google Style, they may not illustrate the only stylish way to represent the code. Optional formatting choices made in examples must not be enforced as rules.
2 Khái niệm cơ bản về tệp nguồn
2.1 Tên tệp
Tên tệp phải là tất cả các chữ thường và có thể bao gồm các dấu gạch dưới [
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
49] hoặc dấu gạch ngang [/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
50], nhưng không có dấu câu bổ sung. Thực hiện theo quy ước mà dự án của bạn sử dụng. Tiện ích mở rộng của FileNames phải là /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
51.2.2 Mã hóa tệp: UTF-8
Các tập tin nguồn được mã hóa trong UTF-8.UTF-8.
2.3 ký tự đặc biệt
2.3.1 ký tự khoảng trắng
Ngoài trình tự kết thúc dòng, ký tự không gian ngang ASCII [0x20] là ký tự khoảng trắng duy nhất xuất hiện ở bất cứ đâu trong tệp nguồn. Điều này ngụ ý rằng
Tất cả các ký tự khoảng trắng khác trong chuỗi chữ được thoát ra, và
Các ký tự tab không được sử dụng để thụt lề.not used for indentation.
2.3.2 Trình tự thoát đặc biệt
Đối với bất kỳ ký tự nào có trình tự thoát đặc biệt [
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
52, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
53, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
54, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
55, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
56, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
57, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
58, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
59, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
60] Legacy Octal Escapes không bao giờ được sử dụng.2.3.3 Các ký tự không phải ASCII
Đối với các ký tự không phải ASCII còn lại, ký tự unicode thực tế [ví dụ:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
64] hoặc thoát Hex hoặc unicode tương đương [ví dụ: /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
65] được sử dụng, chỉ tùy thuộc vào đó làm cho mã dễ đọc và hiểu hơn.easier to read and understand.Mẹo: Trong trường hợp Escape Escape, và đôi khi ngay cả khi các ký tự Unicode thực tế được sử dụng, một nhận xét giải thích có thể rất hữu ích.
/* Best: perfectly clear even without a comment. */
const units = 'μs';
/* Allowed: but unnecessary as μ is a printable character. */
const units = '\u03bcs'; // 'μs'
/* Good: use escapes for non-printable characters with a comment for clarity. */
return '\ufeff' + content; // Prepend a byte order mark.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
Mẹo: Không bao giờ làm cho mã của bạn không thể đọc được chỉ đơn giản là vì sợ rằng một số chương trình có thể không xử lý các ký tự không phải ASCII đúng cách. Nếu điều đó xảy ra, những chương trình đó bị phá vỡ và chúng phải được sửa.broken and they must be fixed.
3 cấu trúc tệp nguồn
Tất cả các tệp nguồn mới phải là tệp
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 [một tệp chứa cuộc gọi /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66] hoặc mô -đun ecmascript [ES] [sử dụng các câu lệnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
68 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
69]. Các tệp bao gồm các tệp sau, theo thứ tự:in order:- Giấy phép hoặc thông tin bản quyền, nếu có mặt
70 JSDOC, nếu có mặt/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
- Tuyên bố
66, nếu tệp/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
66/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
- Các câu lệnh
68, nếu một mô -đun ES/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
- Các câu lệnh
74 và/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
75/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
- Việc triển khai tập tin
Chính xác một dòng trống phân tách mỗi phần có mặt, ngoại trừ việc triển khai của tệp, có thể đi trước 1 hoặc 2 dòng trống. separates each section that is present, except the file's implementation, which may be preceded by 1 or 2 blank lines.
3.1 giấy phép hoặc thông tin bản quyền, nếu có mặt
Nếu giấy phép hoặc thông tin bản quyền thuộc về một tệp, nó thuộc về đây.
3.2 /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
70 JSDOC, nếu có mặt
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
Nhìn thấy ?? cho các quy tắc định dạng.
3.3 /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 Tuyên bố
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
Tất cả các tệp
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 phải khai báo chính xác một tên /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 trên một dòng duy nhất: các dòng chứa khai báo /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 không được gói và do đó là một ngoại lệ đối với giới hạn 80 cột.Toàn bộ đối số với goog.module là những gì xác định một không gian tên. Đó là tên gói [một định danh phản ánh đoạn của cấu trúc thư mục nơi mã sống] cộng với, tùy chọn, lớp chính/enum/giao diện mà nó xác định được liên kết đến cuối.
Thí dụ
goog.module['search.urlHistory.UrlHistoryService'];
3.3.1 Phân cấp
Không gian tên mô -đun có thể không bao giờ được đặt tên là con trực tiếp của không gian tên mô -đun khác.
Disallowed:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
Hệ thống phân cấp thư mục phản ánh hệ thống phân cấp không gian tên, do đó trẻ em được nuôi sâu hơn là các thư mục con của các thư mục phụ huynh cấp cao hơn. Lưu ý rằng điều này ngụ ý rằng chủ sở hữu của các nhóm không gian tên cha mẹ của cha mẹ nhất thiết phải nhận thức được tất cả các không gian tên trẻ em, vì chúng tồn tại trong cùng một thư mục.
3.3.2 /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
81
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
Câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 có thể tùy ý được theo sau bởi một cuộc gọi đến /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
83. Tránh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
84 khi có thể.Example:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
81 tồn tại để dễ dàng chuyển đổi từ các không gian tên dựa trên phân cấp đối tượng truyền thống nhưng đi kèm với một số hạn chế đặt tên. Vì tên mô -đun con phải được tạo theo không gian tên cha, tên này không phải là con hoặc cha mẹ của bất kỳ /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 nào khác [ví dụ: /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
87 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
88 không thể tồn tại an toàn, cũng không thể /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
87 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
90].must not be a child or parent of any other /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 [for example, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
87 and
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
88 cannot both exist safely, nor can /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
87 and /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
90].3.3.3 /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 Xuất khẩu
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
Các lớp, enum, chức năng, hằng số và các ký hiệu khác được xuất bằng đối tượng
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
92. Các ký hiệu được xuất có thể được xác định trực tiếp trên đối tượng /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
92, hoặc nếu không được khai báo cục bộ và xuất khẩu riêng biệt. Các biểu tượng chỉ được xuất nếu chúng được sử dụng bên ngoài mô -đun. Các ký hiệu mô-đun không được xuất chưa được khai báo /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 cũng như tên của chúng kết thúc bằng một dấu gạch dưới. Không có đơn đặt hàng theo quy định cho các ký hiệu xuất khẩu và mô-đun-local.Examples:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
Không chú thích đối tượng
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
92 là /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96 vì nó đã được coi là một hằng số bởi trình biên dịch./** @const */
exports = {exportedFunction};
3.4 Mô -đun ES
3.4.1 Nhập khẩu
Báo cáo nhập không được bao bọc và do đó là một ngoại lệ đối với giới hạn 80 cột.
3.4.1.1 Đường dẫn nhậpCác tệp mô -đun ES phải sử dụng câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
68 để nhập các tệp mô -đun ES khác. Không /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 Mô -đun ES khác.________ 83.4.1.1.1 Tiện ích mở rộng tệp trong đường dẫn nhậpTiện ích mở rộng tệp
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
51 không phải là tùy chọn trong các đường dẫn nhập và phải luôn luôn được đưa vào.import '../directory/file';
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
03.4.1.2 Nhập cùng một tệp nhiều lầnKhông nhập cùng một tệp nhiều lần. Điều này có thể làm cho nó khó xác định nhập khẩu tổng hợp của một tệp.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
13.4.1.3 Đặt tên nhập khẩu3.4.1.3.1 Nhập mô -đun đặt tênTên nhập mô -đun [
goog.module['search.urlHistory.UrlHistoryService'];
00] là các tên goog.module['search.urlHistory.UrlHistoryService'];
01 có nguồn gốc từ tên tệp đã nhập.________ 12 ________ 133.4.1.3.2 Đặt tên nhập khẩu mặc địnhTên nhập mặc định được lấy từ tên tệp đã nhập và tuân theo các quy tắc trong ??.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
4Lưu ý: Nói chung điều này không nên xảy ra khi xuất khẩu mặc định bị cấm bởi hướng dẫn kiểu này, xem ??. Nhập mặc định chỉ được sử dụng để nhập các mô -đun không phù hợp với hướng dẫn kiểu này.
3.4.1.3.3 Đặt tên nhập khẩu được đặt tênTrong các ký hiệu chung được nhập thông qua nhập được đặt tên [
goog.module['search.urlHistory.UrlHistoryService'];
02] sẽ giữ cùng tên. Tránh nhập khẩu bí danh [goog.module['search.urlHistory.UrlHistoryService'];
03]. Thích sửa lỗi va chạm tên bằng cách sử dụng nhập mô -đun [goog.module['search.urlHistory.UrlHistoryService'];
04] hoặc tự đổi tên cho chính xuất khẩu./* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
5Nếu cần đổi tên một lần nhập được đặt tên thì hãy sử dụng các thành phần của tên hoặc đường dẫn tệp của mô -đun đã nhập trong bí danh kết quả.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
63.4.2 Xuất khẩu
Các biểu tượng chỉ được xuất nếu chúng được sử dụng bên ngoài mô -đun. Các ký hiệu mô-đun không được xuất chưa được khai báo
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 cũng như tên của chúng kết thúc bằng một dấu gạch dưới. Không có đơn đặt hàng theo quy định cho các ký hiệu xuất khẩu và mô-đun-local.3.4.2.1 Được đặt tên VS xuất khẩu mặc địnhSử dụng xuất khẩu được đặt tên trong tất cả các mã. Bạn có thể áp dụng từ khóa
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
69 vào khai báo hoặc sử dụng cú pháp goog.module['search.urlHistory.UrlHistoryService'];
07.Không sử dụng xuất khẩu mặc định. Nhập các mô -đun phải đặt tên cho các giá trị này, điều này có thể dẫn đến sự không nhất quán trong việc đặt tên trên các mô -đun.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
7/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
8/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
93.4.2.2 Xuất các lớp và đối tượng container tĩnhKhông xuất các lớp container hoặc đối tượng bằng các phương thức hoặc thuộc tính tĩnh vì mục đích đặt tên.
goog.module['search.urlHistory.UrlHistoryService'];
0Thay vào đó, xuất các hằng số và chức năng riêng lẻ:
goog.module['search.urlHistory.UrlHistoryService'];
13.4.2.3 Khả năng đột biến của xuất khẩuCác biến được xuất không được đột biến bên ngoài khởi tạo mô -đun.
Có những lựa chọn thay thế nếu cần đột biến, bao gồm xuất một tham chiếu không đổi vào một đối tượng có các trường có thể thay đổi hoặc xuất các chức năng truy cập cho dữ liệu có thể thay đổi.
goog.module['search.urlHistory.UrlHistoryService'];
2goog.module['search.urlHistory.UrlHistoryService'];
33.4.2.4 Xuất từCác tuyên bố
goog.module['search.urlHistory.UrlHistoryService'];
08 không được bao bọc và do đó là một ngoại lệ đối với giới hạn 80 cột. Điều này áp dụng cho cả hai hương vị goog.module['search.urlHistory.UrlHistoryService'];
08.goog.module['search.urlHistory.UrlHistoryService'];
43.4.3 Các phụ thuộc tròn trong các mô -đun ES
Không tạo chu kỳ giữa các mô -đun ES, mặc dù đặc điểm kỹ thuật ECMAScript cho phép điều này. Lưu ý rằng có thể tạo các chu kỳ với cả các câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
68 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
69.goog.module['search.urlHistory.UrlHistoryService'];
5goog.module['search.urlHistory.UrlHistoryService'];
6goog.module['search.urlHistory.UrlHistoryService'];
73.4.4 Tương tác với đóng cửa
3.4.4.1 Tham khảo GoogĐể tham khảo không gian tên đóng
goog.module['search.urlHistory.UrlHistoryService'];
12, nhập goog.module['search.urlHistory.UrlHistoryService'];
13 của đóng.goog.module['search.urlHistory.UrlHistoryService'];
8goog.module['search.urlHistory.UrlHistoryService'];
13 chỉ xuất một tập hợp các thuộc tính từ toàn cầu goog.module['search.urlHistory.UrlHistoryService'];
12 có thể được sử dụng trong các mô -đun ES.3.4.4.2 Goog.Require trong các mô -đun ES/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 trong các mô -đun ES hoạt động như trong các tệp /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66. Bạn có thể yêu cầu bất kỳ ký hiệu không gian tên đóng nào [nghĩa là các ký hiệu được tạo bởi goog.module['search.urlHistory.UrlHistoryService'];
18 hoặc /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66] và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 sẽ trả về giá trị.goog.module['search.urlHistory.UrlHistoryService'];
93.4.4.3 Khai báo ID mô -đun đóng trong các mô -đun ESgoog.module['search.urlHistory.UrlHistoryService'];
21 có thể được sử dụng trong các mô-đun ES để khai báo ID mô-đun giống như ____ 166. Điều này có nghĩa là ID mô -đun này có thể là /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74D, goog.module['search.urlHistory.UrlHistoryService'];
24D, ________ 225'd, v.v. Như thể đó là một /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 không gọi /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
81. Nó không tạo ID mô -đun dưới dạng biểu tượng JavaScript có sẵn trên toàn cầu.A Do đó, đối số của
goog.module['search.urlHistory.UrlHistoryService'];
21 phải luôn kết thúc bằng một goog.module['search.urlHistory.UrlHistoryService'];
33.Lưu ý: Đó là một lỗi khi gọi
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
81 trong một mô -đun ES, nó chỉ có thể được gọi từ các tệp /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66. Không có cách trực tiếp để liên kết một không gian tên di sản với một mô -đun ES.goog.module['search.urlHistory.UrlHistoryService'];
21 chỉ nên được sử dụng để nâng cấp các tệp đóng lên các mô -đun ES tại chỗ, nơi sử dụng xuất khẩu được đặt tên.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
03.5 goog.module['search.urlHistory.UrlHistoryService'];
37
goog.module['search.urlHistory.UrlHistoryService'];
Trong tệp
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66, câu lệnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 có thể tùy ý được theo sau bởi một cuộc gọi đến goog.module['search.urlHistory.UrlHistoryService'];
40.Trong một mô -đun ES, các câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
68 có thể tùy ý được theo sau bởi một cuộc gọi đến goog.module['search.urlHistory.UrlHistoryService'];
40.3.6 /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
Nhập khẩu được thực hiện với các câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75. Các tên được nhập bởi một câu lệnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 có thể được sử dụng cả trong mã và trong các chú thích loại, trong khi các tên được nhập bởi /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 chỉ có thể được sử dụng trong các chú thích loại.Các câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 tạo thành một khối liền kề không có đường trống. Khối này tuân theo tuyên bố /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 được phân tách bằng một dòng trống duy nhất. Toàn bộ đối số cho /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 hoặc /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 là không gian tên được xác định bởi /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 trong một tệp riêng. Các câu lệnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 có thể không xuất hiện ở bất kỳ nơi nào khác trong tệp.Mỗi
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 hoặc /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 được gán cho một bí danh không đổi, hoặc nếu không sẽ bị phá hủy thành một số bí danh không đổi. Những bí danh này là cách duy nhất được chấp nhận để đề cập đến các phụ thuộc trong các chú thích hoặc mã loại. Không được sử dụng các không gian tên đủ điều kiện ở bất cứ đâu, ngoại trừ như một đối số với /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 hoặc /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75.Ngoại lệ: Các loại, biến và chức năng được khai báo trong các tệp bên ngoài phải sử dụng tên đủ điều kiện của chúng trong các chú thích và mã loại.: Types, variables, and functions declared in externs files have to use their fully qualified name in type annotations and code.
Bí danh phải khớp với thành phần phân tách chấm cuối cùng của không gian tên của mô-đun đã nhập.
Ngoại lệ: Trong một số trường hợp nhất định, các thành phần bổ sung của không gian tên có thể được sử dụng để tạo thành một bí danh dài hơn. Bí danh kết quả phải giữ lại vỏ của định danh ban đầu sao cho nó vẫn xác định chính xác loại của nó. Bí danh dài hơn có thể được sử dụng để phân loại các bí danh giống hệt nhau hoặc nếu nó cải thiện đáng kể khả năng đọc. Ngoài ra, phải sử dụng bí danh dài hơn để ngăn chặn các loại bản địa như
61, goog.module['search.urlHistory.UrlHistoryService'];
62, goog.module['search.urlHistory.UrlHistoryService'];
63, goog.module['search.urlHistory.UrlHistoryService'];
64 và goog.module['search.urlHistory.UrlHistoryService'];
65 [để biết danh sách đầy đủ hơn, hãy xem các đối tượng tích hợp tiêu chuẩn và API Web tại MDN]. Khi đổi tên bí danh bị phá hủy, một không gian phải tuân theo đại tràng theo yêu cầu trong ??.: In certain cases, additional components of the namespace can be used to form a longer alias. The resulting alias must retain the original identifier's casing such that it still correctly identifies its type. Longer aliases may be used to
disambiguate otherwise identical aliases, or if it significantly improves readability. In addition, a longer alias must be used to prevent masking native types such as goog.module['search.urlHistory.UrlHistoryService'];
goog.module['search.urlHistory.UrlHistoryService'];
61, goog.module['search.urlHistory.UrlHistoryService'];
62, goog.module['search.urlHistory.UrlHistoryService'];
63, goog.module['search.urlHistory.UrlHistoryService'];
64, and goog.module['search.urlHistory.UrlHistoryService'];
65 [for a more complete list, see Standard Built-in Objects and Web APIs at MDN]. When
renaming destructured aliases, a space must follow the colon as required in ??.Một tệp không nên chứa cả câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 cho cùng một không gian tên. Nếu tên đã nhập được sử dụng cả trong mã và trong các chú thích loại, nó sẽ được nhập bằng một câu lệnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74.Nếu một mô -đun chỉ được nhập cho các tác dụng phụ của nó, cuộc gọi phải là một
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 [không phải là /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75] và có thể bị bỏ qua. Một nhận xét là cần thiết để giải thích lý do tại sao điều này là cần thiết và đàn áp cảnh báo trình biên dịch.Các dòng được sắp xếp theo các quy tắc sau: Tất cả đều yêu cầu với tên ở phía bên trái đến trước, được sắp xếp theo thứ tự bảng chữ cái theo các tên đó. Sau đó, sự phá hủy yêu cầu, một lần nữa được sắp xếp theo tên ở phía bên trái. Cuối cùng, mọi yêu cầu gọi là độc lập [nói chung chúng là dành cho các mô -đun được nhập chỉ vì tác dụng phụ của chúng].
Mẹo: Không cần phải ghi nhớ lệnh này và thực thi thủ công. Bạn có thể dựa vào IDE của mình để báo cáo yêu cầu không được sắp xếp chính xác.
Nếu một bí danh dài hoặc tên mô-đun sẽ khiến một dòng vượt quá giới hạn 80 cột, thì không được gói: yêu cầu các dòng là một ngoại lệ đối với giới hạn 80 cột.must not be wrapped: require lines are an exception to the 80-column limit.
Example:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
1Discouraged:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
2Disallowed:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33.7 Việc triển khai tệp
Việc thực hiện thực tế theo sau sau khi tất cả thông tin phụ thuộc được khai báo [cách nhau bởi ít nhất một dòng trống].
Điều này có thể bao gồm bất kỳ khai báo mô-đun địa phương [hằng số, biến, lớp, chức năng, v.v.], cũng như bất kỳ ký hiệu được xuất nào.
4 định dạng
Thuật ngữ Lưu ý: Xây dựng giống như khối đề cập đến phần thân của một lớp, chức năng, phương thức hoặc khối mã được phân tách bằng niềng. Lưu ý rằng, bởi ?? và ??, bất kỳ mảng hoặc đối tượng theo nghĩa đen nào có thể được đối xử như thể nó là một cấu trúc giống như khối.: block-like construct refers to the body of a class, function, method, or brace-delimited block of code. Note that, by ?? and ??, any array or object literal may optionally be treated as if it were a block-like construct.
Mẹo: Sử dụng
goog.module['search.urlHistory.UrlHistoryService'];
71. Cộng đồng JavaScript đã đầu tư nỗ lực để đảm bảo Clang-Format thực hiện đúng trên các tệp JavaScript. goog.module['search.urlHistory.UrlHistoryService'];
71 có tích hợp với một số biên tập viên phổ biến.4.1 niềng răng
4.1.1 Niềng răng được sử dụng cho tất cả các cấu trúc điều khiển
Niềng răng được yêu cầu cho tất cả các cấu trúc điều khiển [nghĩa là
goog.module['search.urlHistory.UrlHistoryService'];
73, goog.module['search.urlHistory.UrlHistoryService'];
74, goog.module['search.urlHistory.UrlHistoryService'];
75, goog.module['search.urlHistory.UrlHistoryService'];
76, goog.module['search.urlHistory.UrlHistoryService'];
77, cũng như bất kỳ ai khác], ngay cả khi cơ thể chỉ chứa một câu lệnh. Tuyên bố đầu tiên của một khối không trống phải bắt đầu trên dòng riêng của nó.Disallowed:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
4Ngoại lệ: Một câu lệnh đơn giản nếu có thể phù hợp hoàn toàn trên một dòng không có gói [và điều đó không có một điều khác] có thể được giữ trên một dòng không có niềng răng khi nó cải thiện khả năng đọc. Đây là trường hợp duy nhất trong đó cấu trúc điều khiển có thể bỏ qua niềng răng và newlines.: A simple if statement that can fit entirely on a single line with no wrapping [and that doesn’t have an else] may be kept on a single line with no braces when it improves readability. This is the only case in which a control structure may omit braces and newlines.
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
54.1.2 Khối không trống: Kiểu K & R
Niềng răng theo phong cách Kernighan và Ritchie [khung Ai Cập] cho các khối không trống và các cấu trúc giống như khối:
- Không có đường ngắt trước khi nẹp mở.
- Dòng phá vỡ sau khi nẹp mở.
- Dòng phá vỡ trước khi nẹp đóng.
- Phá vỡ dòng sau khi đóng niềng răng nếu niềng răng đó chấm dứt câu lệnh hoặc phần thân của hàm hoặc câu lệnh lớp hoặc phương pháp lớp. Cụ thể, không có đường ngắt sau khi nẹp nếu được theo sau bởi
74,goog.module['search.urlHistory.UrlHistoryService'];
79,goog.module['search.urlHistory.UrlHistoryService'];
77 hoặc dấu phẩy, dấu chấm phẩy hoặc phần tử phải.goog.module['search.urlHistory.UrlHistoryService'];
Thí dụ:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
64.1.3 Khối trống: Có thể ngắn gọn
Một khối trống hoặc cấu trúc giống như khối có thể được đóng ngay sau khi nó được mở, không có ký tự, không gian hoặc đường ngắt ở giữa [nghĩa là
goog.module['search.urlHistory.UrlHistoryService'];
81], trừ khi nó là một phần của câu lệnh đa khối [một câu trực tiếp chứa nhiều Khối: ________ 273/________ 274 hoặc ________ 284/________ 279/________ 286].unless it is a part of a multi-block statement [one that directly contains multiple blocks: goog.module['search.urlHistory.UrlHistoryService'];
73/goog.module['search.urlHistory.UrlHistoryService'];
74 or goog.module['search.urlHistory.UrlHistoryService'];
84/goog.module['search.urlHistory.UrlHistoryService'];
79/goog.module['search.urlHistory.UrlHistoryService'];
86].Example:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
7Disallowed:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
84.2 Khối thụt: +2 không gian
Mỗi lần mở một khối hoặc cấu trúc giống như khối mới, thụt lề tăng thêm hai khoảng trắng. Khi khối kết thúc, vết lõm trở lại mức thụt đầu trước. Cấp độ thụt áp dụng cho cả mã và nhận xét trong suốt khối. [Xem ví dụ trong ??].
4
Bất kỳ mảng nào theo nghĩa đen có thể tùy ý được định dạng như thể nó là một cấu trúc giống như khối. Ví dụ: sau đây đều hợp lệ [không phải là danh sách đầy đủ]:not an exhaustive list]:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
9goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
0Các kết hợp khác được cho phép, đặc biệt khi nhấn mạnh các nhóm ngữ nghĩa giữa các yếu tố, nhưng không nên được sử dụng để giảm kích thước thẳng đứng của các mảng lớn hơn.
4.2.2 BÀI VIẾT Đối tượng: Tùy chọn Khối giống như khối
Bất kỳ đối tượng nào theo nghĩa đen có thể tùy ý được định dạng như thể nó là một cấu trúc giống như khối. Các ví dụ tương tự áp dụng như ??. Ví dụ: sau đây đều hợp lệ [không phải là danh sách đầy đủ]:not an exhaustive list]:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
1goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
24.2.3 Lớp học
Lớp học [cho dù khai báo hoặc biểu thức] được thụt vào làm khối. Không thêm dấu chấm phẩy sau các phương pháp, hoặc sau khi đóng cửa của một tuyên bố lớp [các câu lệnh, ví dụ như các bài tập mà có chứa các biểu thức lớp vẫn bị chấm dứt bằng dấu chấm phẩy]. Sử dụng từ khóa
goog.module['search.urlHistory.UrlHistoryService'];
87, nhưng không phải là chú thích goog.module['search.urlHistory.UrlHistoryService'];
88 JSDOC trừ khi lớp mở rộng một loại tạm thời.Example:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
3goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
44.2.4 Biểu thức chức năng
Khi khai báo một hàm ẩn danh trong danh sách các đối số cho một cuộc gọi chức năng, phần thân của hàm được thụt vào hai khoảng trắng nhiều hơn độ sâu thụt trước.
Example:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
54.2.5 Câu lệnh chuyển đổi
Như với bất kỳ khối nào khác, nội dung của một khối chuyển đổi được thụt vào +2.
Sau khi một nhãn chuyển đổi, một dòng mới xuất hiện và mức thụt được tăng +2, chính xác như thể một khối được mở. Một khối rõ ràng có thể được sử dụng nếu được yêu cầu bởi phạm vi từ vựng. Nhãn chuyển đổi sau đây trở về cấp độ thụt trước đó, như thể một khối đã bị đóng.
Một dòng trống là tùy chọn giữa
goog.module['search.urlHistory.UrlHistoryService'];
89 và trường hợp sau.Example:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
64.3 Báo cáo
4.3.1 Một tuyên bố trên mỗi dòng
Mỗi câu lệnh được theo sau bởi một dòng phá vỡ.
4.3.2 Semicolons được yêu cầu
Mỗi tuyên bố phải được chấm dứt với một dấu chấm phẩy. Dựa vào việc chèn dấu chấm phẩy tự động bị cấm.
Giới hạn cột 4,4: 80
Mã JavaScript có giới hạn cột là 80 ký tự. Trừ khi có lưu ý dưới đây, bất kỳ dòng nào sẽ vượt quá giới hạn này phải được bọc dòng, như được giải thích trong ??.
Exceptions:
66,/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
74 và/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
75 [xem ?? và ??]./* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
- Mô -đun ES
68 và/* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
08 [xem ?? và ??].goog.module['search.urlHistory.UrlHistoryService'];
- Các dòng không thể tuân theo giới hạn cột là không thể hoặc sẽ cản trở khả năng khám phá. Những ví dụ bao gồm:
- Một URL dài nên có thể nhấp trong nguồn.
- Một lệnh shell dự định sẽ được sao chép và thực hiện.
- Một chuỗi dài theo nghĩa đen có thể cần được sao chép hoặc tìm kiếm toàn bộ [ví dụ: một đường dẫn tệp dài].
4,5 bao bọc dòng
Thuật ngữ Lưu ý: Gói dòng đang phá vỡ một đoạn mã thành nhiều dòng để tuân theo giới hạn cột, trong đó khối có thể phù hợp về mặt pháp lý trong một dòng.: Line wrapping is breaking a chunk of code into multiple lines to obey column limit, where the chunk could otherwise legally fit in a single line.
Không có công thức toàn diện, xác định cho thấy chính xác cách bao bọc dòng trong mọi tình huống. Rất thường có một số cách hợp lệ để bao bọc dòng cùng một đoạn mã.
Lưu ý: Mặc dù lý do điển hình cho việc bao bọc dòng là để tránh tràn ra giới hạn cột, nhưng ngay cả mã thực tế sẽ phù hợp trong giới hạn cột có thể được bao bọc theo quyết định của tác giả.
Mẹo: Trích xuất một phương pháp hoặc biến cục bộ có thể giải quyết vấn đề mà không cần bao bọc dòng.
4.5.1 Ở đâu để phá vỡ
Chỉ thị chính của việc bao bọc dòng là: thích phá vỡ ở cấp độ cú pháp cao hơn.higher syntactic level.
Preferred:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
7Discouraged:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
8Trong ví dụ trước, các mức cú pháp từ cao nhất đến thấp nhất như sau: gán, phân chia, gọi chức năng, tham số, hằng số số.
Các nhà khai thác được bọc như sau:
- Khi một dòng bị phá vỡ tại một toán tử, giờ nghỉ sẽ xuất hiện sau biểu tượng. [Lưu ý rằng đây không phải là thực tiễn tương tự được sử dụng trong Google Style cho Java.]
- Điều này không áp dụng cho dấu chấm [
95], thực sự không phải là người vận hành.goog.module['search.urlHistory.UrlHistoryService'];
- Điều này không áp dụng cho dấu chấm [
- Một tên phương thức hoặc tên tạo hàm được gắn vào dấu ngoặc đơn mở [
96] theo sau nó.goog.module['search.urlHistory.UrlHistoryService'];
- Một dấu phẩy [
97] được gắn vào mã thông báo trước nó.goog.module['search.urlHistory.UrlHistoryService'];
Lưu ý: Mục tiêu chính cho gói dòng là có mã rõ ràng, không nhất thiết phải là mã phù hợp với số lượng nhỏ nhất.
4.5.2 Các dòng tiếp tục thụt vào ít nhất +4 không gian
Khi bao bọc dòng, mỗi dòng sau lần đầu tiên [mỗi dòng tiếp tục] được thụt vào ít nhất +4 từ dòng ban đầu, trừ khi nó nằm trong các quy tắc của thụt khối.
Khi có nhiều dòng tiếp tục, thụt có thể được thay đổi ngoài +4 khi thích hợp. Nói chung, các dòng tiếp tục ở cấp độ cú pháp sâu hơn được thụt tính bởi các bội số lớn hơn của 4 và hai dòng sử dụng cùng một mức thụt vào khi và chỉ khi chúng bắt đầu với các phần tử song song cú pháp.
?? giải quyết việc thực hành không nản lòng khi sử dụng một số lượng không gian thay đổi để sắp xếp các mã thông báo nhất định với các dòng trước đó.
4.6 Whitespace
4.6.1 khoảng trắng dọc
Một dòng trống duy nhất xuất hiện:
- Giữa các phương pháp liên tiếp trong một lớp hoặc đối tượng theo nghĩa đen
- Ngoại lệ: Một dòng trống giữa hai định nghĩa thuộc tính liên tiếp theo nghĩa đen của một đối tượng [không có mã nào khác giữa chúng] là tùy chọn. Những dòng trống như vậy được sử dụng khi cần thiết để tạo các nhóm hợp lý của các trường.
- Trong các cơ quan phương pháp, một cách tiết kiệm để tạo ra các nhóm câu lệnh logic. Các đường trống ở đầu hoặc cuối của một cơ thể chức năng không được phép.
- Tùy chọn trước phương pháp đầu tiên hoặc sau phương pháp cuối cùng trong một lớp hoặc đối tượng theo nghĩa đen [không được khuyến khích cũng không nản lòng].
- Theo yêu cầu của các phần khác của tài liệu này [ví dụ: ??].
Nhiều dòng trống liên tiếp được cho phép, nhưng không bao giờ được yêu cầu [cũng không được khuyến khích].
4.6.2 khoảng trắng ngang
Việc sử dụng khoảng trắng ngang phụ thuộc vào vị trí và rơi vào ba loại rộng: dẫn đầu [khi bắt đầu một dòng], theo dõi [ở cuối một dòng] và nội bộ. Khoảng cách hàng đầu [tức là, thụt lề] được giải quyết ở nơi khác. Trailing Whitespace bị cấm.
Ngoài các yêu cầu của ngôn ngữ hoặc các quy tắc phong cách khác, và ngoài các chữ, nhận xét và JSDOC, một không gian ASCII nội bộ duy nhất còn xuất hiện ở những nơi sau.only.
- Tách bất kỳ từ dành riêng nào [chẳng hạn như
73,goog.module['search.urlHistory.UrlHistoryService'];
75 hoặcgoog.module['search.urlHistory.UrlHistoryService'];
79] ngoại trừgoog.module['search.urlHistory.UrlHistoryService'];
01 vàgoog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
02, từ dấu ngoặc đơn mở [goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
96] theo nó trên dòng đó.goog.module['search.urlHistory.UrlHistoryService'];
- Tách bất kỳ từ dành riêng nào [chẳng hạn như
74 hoặcgoog.module['search.urlHistory.UrlHistoryService'];
79] khỏi một nẹp xoăn đóng [goog.module['search.urlHistory.UrlHistoryService'];
06] đi trước nó trên dòng đó.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Trước khi có niềng răng xoăn mở [
07], với hai ngoại lệ:goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Trước một đối tượng theo nghĩa đen là đối số đầu tiên của hàm hoặc phần tử đầu tiên trong một mảng theo nghĩa đen [ví dụ:
08].goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Trong một bản mở rộng mẫu, vì nó bị cấm bởi ngôn ngữ [ví dụ: hợp lệ:
09, không hợp lệ:goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
10].goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Trước một đối tượng theo nghĩa đen là đối số đầu tiên của hàm hoặc phần tử đầu tiên trong một mảng theo nghĩa đen [ví dụ:
- Ở cả hai phía của bất kỳ toán tử nhị phân hoặc ternary.
- Sau một dấu phẩy [
97] hoặc dấu chấm phẩy [goog.module['search.urlHistory.UrlHistoryService'];
12]. Lưu ý rằng không gian không bao giờ được phép trước các ký tự này.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Sau đại tràng [
13] trong một đối tượng theo nghĩa đen.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Ở cả hai phía của chém đôi [
14] bắt đầu một nhận xét cuối cùng. Ở đây, nhiều không gian được cho phép, nhưng không bắt buộc.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Sau một ký tự nhận xét khối mở và ở cả hai mặt của ký tự gần [ví dụ: đối với các khai báo loại ngắn, phôi và tên tham số Nhận xét:
15; hoặcgoog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
16; hoặcgoog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
17].goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
4.6.3 Căn chỉnh ngang: Không nản lòng
Thuật ngữ Lưu ý: Căn chỉnh theo chiều ngang là thực tiễn thêm một số lượng không gian bổ sung trong mã của bạn với mục tiêu làm cho các mã thông báo nhất định xuất hiện ngay bên dưới một số mã thông báo khác trên các dòng trước.: Horizontal alignment is the practice of adding a variable number of additional spaces in your code with the goal of making certain tokens appear directly below certain other tokens on previous lines.
Thực tiễn này được cho phép, nhưng nó thường không được khuyến khích bởi phong cách Google. Thậm chí không cần phải duy trì sự liên kết ngang ở những nơi đã được sử dụng.generally discouraged by Google Style. It is not even required to maintain horizontal alignment in places where it was already used.
Dưới đây là một ví dụ mà không liên kết, theo sau là một với sự liên kết. Cả hai đều được phép, nhưng sau này không được khuyến khích:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
9Mẹo: Căn chỉnh có thể hỗ trợ khả năng đọc, nhưng nó tạo ra vấn đề cho việc bảo trì trong tương lai. Hãy xem xét một sự thay đổi trong tương lai cần chỉ chạm vào một dòng. Sự thay đổi này có thể để lại định dạng trước đây bị xáo trộn, và điều đó được cho phép. Thông thường, nó cũng nhắc nhở các lập trình viên [có lẽ bạn] cũng điều chỉnh khoảng trắng trên các dòng gần đó, có thể kích hoạt một loạt các định dạng lại. Sự thay đổi một dòng đó bây giờ có bán kính nổ. Điều này có thể dẫn đến điều tồi tệ nhất trong việc bận rộn vô nghĩa, nhưng tốt nhất là nó vẫn làm hỏng thông tin lịch sử phiên bản, làm chậm người đánh giá và làm trầm trọng thêm xung đột hợp nhất.
4.6.4 Đối số chức năng
Thích đặt tất cả các đối số chức năng trên cùng một dòng với tên hàm. Nếu làm như vậy sẽ vượt quá giới hạn 80 cột, các đối số phải được bọc theo một cách có thể đọc được. Để tiết kiệm không gian, bạn có thể bao bọc càng gần 80 càng tốt hoặc đặt mỗi đối số trên dòng riêng của mình để tăng cường khả năng đọc. Th thụt lề nên là bốn không gian. Căn chỉnh với dấu ngoặc đơn được cho phép, nhưng không được khuyến khích. Dưới đây là các mẫu phổ biến nhất để gói đối số:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
04.7 Dấu ngoặc nhóm: Khuyến nghị
Dấu ngoặc nhóm tùy chọn chỉ được bỏ qua khi tác giả và người đánh giá đồng ý rằng không có cơ hội hợp lý rằng mã sẽ bị giải thích sai nếu không có chúng, họ cũng sẽ không làm cho mã dễ đọc hơn. Không hợp lý khi cho rằng mọi người đọc đều có toàn bộ bảng điều khiển toán tử được ghi nhớ.
Không sử dụng dấu ngoặc đơn không cần thiết xung quanh toàn bộ biểu thức sau
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
18, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
19, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
20, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
21, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
22, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
23, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
24, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
25 hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
26.Dấu ngoặc đơn được yêu cầu cho các loại phôi:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
27.Phần này giải quyết các ý kiến thực hiện. JSDOC được giải quyết riêng trong ??.
Nhận xét khối được thụt vào ở cùng cấp độ với mã xung quanh. Họ có thể ở trong
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
28 hoặc ________ 314 theo phong cách. Đối với các nhận xét đa dòng ____328, các dòng tiếp theo phải bắt đầu với * được liên kết với goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
31 trên dòng trước, để làm cho nhận xét rõ ràng mà không có bối cảnh bổ sung.const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
1Nhận xét không được đặt trong các hộp được vẽ bằng dấu hoa thị hoặc các ký tự khác.
Không sử dụng JSDOC [
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
48] để nhận xét thực hiện.Tên tham số Thông số Nhận xét nên được sử dụng bất cứ khi nào giá trị và tên phương thức không đủ truyền tải ý nghĩa và tái cấu trúc phương pháp để rõ ràng hơn là không khả thi. Định dạng ưa thích của chúng là trước giá trị với =:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
2Để có tính nhất quán với mã xung quanh, bạn có thể đặt chúng sau giá trị mà không có =:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
35 tính năng ngôn ngữ
JavaScript bao gồm nhiều tính năng đáng ngờ [và thậm chí nguy hiểm]. Phần này phân định các tính năng có thể hoặc không được sử dụng và bất kỳ ràng buộc bổ sung nào về việc sử dụng chúng.
5.1 Khai báo biến cục bộ
5.1.1 Sử dụng goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33 và goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
34
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
Khai báo tất cả các biến cục bộ với
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33 hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
34. Sử dụng const theo mặc định, trừ khi một biến cần được chỉ định lại. Từ khóa goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 không được sử dụng.5.1.2 Một biến cho mỗi tuyên bố
Mỗi tuyên bố biến cục bộ chỉ khai báo một biến: các khai báo như
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
38 không được sử dụng.5.1.3 được khai báo khi cần, khởi tạo càng sớm càng tốt
Các biến cục bộ không được khai báo theo thói quen khi bắt đầu cấu trúc khối hoặc khối chứa của chúng. Thay vào đó, các biến cục bộ được khai báo gần với điểm chúng được sử dụng lần đầu tiên [trong lý do], để giảm thiểu phạm vi của chúng.not habitually declared at the start of their containing block or block-like construct. Instead, local variables are declared close to the point they are first used [within reason], to minimize their scope.
5.1.4 Các loại khai báo khi cần thiết
Chú thích loại JSDOC có thể được thêm vào dòng trên khai báo, hoặc nếu không nội tuyến trước tên biến nếu không có JSDOC nào khác.
Example:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
4Không cho phép các kiểu Inline và JSDOC không được phép: trình biên dịch sẽ chỉ xử lý JSDOC đầu tiên và các chú thích nội tuyến sẽ bị mất.
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
5Mẹo: Có nhiều trường hợp trình biên dịch có thể suy ra một loại templatized nhưng không phải là tham số của nó. Điều này đặc biệt là trường hợp khi cuộc gọi khởi tạo theo nghĩa đen hoặc hàm tạo không bao gồm bất kỳ giá trị nào của loại tham số mẫu [ví dụ: các mảng trống, đối tượng,
goog.module['search.urlHistory.UrlHistoryService'];
64S hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
40s] hoặc nếu biến được sửa đổi trong việc đóng. Chú thích loại biến cục bộ đặc biệt hữu ích trong các trường hợp này vì nếu không trình biên dịch sẽ suy ra tham số mẫu là không xác định.5.2 Mảng nghĩa đen
5.2.1 Sử dụng dấu phẩy kéo dài
Bao gồm một dấu phẩy kéo dài bất cứ khi nào có sự phá vỡ dòng giữa phần tử cuối cùng và khung đóng.
Example:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
65.2.2 Không sử dụng hàm tạo goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
41 Variadic
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
Hàm tạo có dễ bị lỗi nếu các đối số được thêm hoặc xóa. Sử dụng một nghĩa đen thay thế.
Disallowed:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
7Điều này hoạt động như mong đợi ngoại trừ trường hợp thứ ba: nếu
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
42 là một số toàn bộ thì goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
43 là một mảng có kích thước goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
42 trong đó tất cả các yếu tố là goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
45. Nếu goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
42 là bất kỳ số nào khác, thì một ngoại lệ sẽ được ném và nếu nó là bất cứ điều gì khác thì nó sẽ là một mảng một phần tử.Thay vào đó, hãy viết
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
8Phân bổ rõ ràng một mảng có độ dài nhất định bằng cách sử dụng
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
47 được cho phép khi thích hợp.5.2.3 Thuộc tính không phải là số
Không xác định hoặc sử dụng các thuộc tính không phải là số trên một mảng [trừ
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
48]. Thay vào đó, sử dụng goog.module['search.urlHistory.UrlHistoryService'];
64 [hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
50].5.2.4 Phá hủy
Các chữ cái có thể được sử dụng ở phía bên trái của một gán để thực hiện phá hủy [chẳng hạn như khi giải nén nhiều giá trị từ một mảng hoặc có thể lặp lại]. Một phần tử nghỉ cuối cùng có thể được bao gồm [không có khoảng trống giữa
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
51 và tên biến]. Các yếu tố nên được bỏ qua nếu chúng không được sử dụng.const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
9Phá hủy cũng có thể được sử dụng cho các tham số chức năng [lưu ý rằng tên tham số được yêu cầu nhưng bị bỏ qua]. Luôn chỉ định
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
52 là giá trị mặc định nếu tham số mảng bị phá hủy là tùy chọn và cung cấp các giá trị mặc định ở phía bên trái:/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
0Disallowed:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
1Mẹo: Đối với [un] đóng gói nhiều giá trị vào tham số hoặc trả về hàm, thích phá hủy đối tượng để phá hủy mảng khi có thể, vì nó cho phép đặt tên cho các phần tử riêng lẻ và chỉ định một loại khác nhau cho mỗi phần tử.
5.2.5 Nhà điều hành lây lan
Các văn bản mảng có thể bao gồm toán tử lây lan [
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
51] để làm phẳng các phần tử ra khỏi một hoặc nhiều lần lặp khác. Toán tử lây lan nên được sử dụng thay vì các cấu trúc khó xử hơn với goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
54. Không có không gian sau goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
51.Example:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
25.3 đối tượng theo nghĩa đen
5.3.1 Sử dụng dấu phẩy kéo dài
Bao gồm một dấu phẩy kéo dài bất cứ khi nào có một dòng phá vỡ giữa tài sản cuối cùng và nẹp đóng.
5.3.2 Không sử dụng hàm tạo goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
50
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
Mặc dù
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
50 không có vấn đề tương tự như goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
41, nhưng nó vẫn không được phép cho tính nhất quán. Thay vào đó, sử dụng một đối tượng [goog.module['search.urlHistory.UrlHistoryService'];
81 hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
60].5.3.3 Không trộn các phím được trích dẫn và chưa được trích dẫn
Các chữ cái có thể đại diện cho một trong hai cấu trúc [với các khóa và/hoặc ký hiệu chưa được trích xuất] hoặc các dicts [với các khóa được trích dẫn và/hoặc tính toán]. Không trộn các loại khóa này trong một đối tượng theo nghĩa đen.
Disallowed:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
3Điều này cũng mở rộng để chuyển tên tài sản cho các chức năng, như
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
61. Cụ thể, làm như vậy sẽ phá vỡ mã được biên dịch vì trình biên dịch không thể đổi tên/obfuscate chuỗi chữ.Disallowed:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
4Điều này được thực hiện tốt nhất như:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
55.3.4 Tên thuộc tính được tính toán
Tên thuộc tính được tính toán [ví dụ:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
62] được cho phép và được coi là các khóa theo kiểu Dictyle [trích dẫn] [tức là, không được trộn với các khóa không được trích xuất] trừ khi thuộc tính được tính toán là một ký hiệu [ví dụ: goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
63]. Các giá trị enum cũng có thể được sử dụng cho các khóa tính toán, nhưng không nên được trộn với các phím không EREM trong cùng một chữ.5.3.5 Phương pháp tốc ký
Các phương pháp có thể được định nghĩa trên các chữ cái đối tượng bằng phương pháp tốc ký [
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
64] thay cho đại tràng ngay sau đó là goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
01 hoặc hàm mũi tên theo nghĩa đen.Thí dụ:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
6Lưu ý rằng
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66 trong một phương pháp tốc ký hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
01 đề cập đến chính đối tượng theo nghĩa đen trong khi goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66 trong hàm mũi tên đề cập đến phạm vi bên ngoài đối tượng theo nghĩa đen.Example:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
75.3.6 Tính chất tốc ký
Các thuộc tính tốc ký được cho phép trên các nghĩa đen đối tượng.
Example:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
85.3.7 Phá hủy
Các mẫu phá hủy đối tượng có thể được sử dụng ở phía bên trái của một gán để thực hiện phá hủy và giải nén nhiều giá trị khỏi một đối tượng.
Các đối tượng bị phá hủy cũng có thể được sử dụng làm tham số chức năng, nhưng nên được giữ đơn giản nhất có thể: một mức độ duy nhất của các thuộc tính tốc ký chưa được trích xuất. Mức độ sâu hơn của các thuộc tính làm tổ và tính toán có thể không được sử dụng trong phá hủy tham số. Chỉ định bất kỳ giá trị mặc định nào ở phía bên trái của tham số bị phá hủy [
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
69, thay vì goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
70] và nếu một đối tượng bị phá hủy là tùy chọn, nó phải mặc định là goog.module['search.urlHistory.UrlHistoryService'];
81. JSDOC cho tham số bị phá hủy có thể được đặt bất kỳ tên nào [tên không được sử dụng nhưng được yêu cầu bởi trình biên dịch].Example:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
9Disallowed:
/** @const */
exports = {exportedFunction};
0Phá hủy cũng có thể được sử dụng cho các tuyên bố
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74, và trong trường hợp này không được gói: toàn bộ tuyên bố chiếm một dòng, bất kể nó là bao lâu [xem ??].5.3.8 Enums
Các liệt kê được xác định bằng cách thêm chú thích
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
73 vào một đối tượng theo nghĩa đen. Các thuộc tính bổ sung có thể không được thêm vào một enum sau khi nó được xác định. Các enum phải không đổi, và tất cả các giá trị enum phải là bất biến sâu sắc./** @const */
exports = {exportedFunction};
15.4 lớp
5.4.1 Chất xây dựng
Người xây dựng là tùy chọn. Các trình xây dựng lớp con phải gọi
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
74 trước khi đặt bất kỳ trường nào hoặc truy cập goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66. Các giao diện nên khai báo các thuộc tính phi phương pháp trong hàm tạo.5.4.2 Trường
Đặt tất cả các trường đối tượng cụ thể [nghĩa là tất cả các thuộc tính khác ngoài các phương thức] trong hàm tạo. Các trường chú thích không bao giờ được gán lại bằng
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96 [những trường này không cần phải là bất biến sâu sắc]. Chú thích các trường không công khai với chú thích khả năng hiển thị thích hợp [/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
78, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
79], và kết thúc tất cả các tên của /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 với một dấu gạch dưới. Các trường không bao giờ được đặt trên một lớp cụ thể 'goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
81.Example:
/** @const */
exports = {exportedFunction};
2Mẹo: Các thuộc tính không bao giờ nên được thêm vào hoặc loại bỏ khỏi một trường hợp sau khi hàm tạo kết thúc, vì nó cản trở đáng kể khả năng tối ưu hóa VMS VMS. Nếu cần thiết, các trường được khởi tạo sau này phải được đặt rõ ràng thành
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
45 trong hàm tạo để ngăn chặn các thay đổi hình dạng sau này. Thêm goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
83 vào một đối tượng sẽ kiểm tra xem các thuộc tính không được khai báo không được thêm/truy cập. Các lớp có điều này được thêm theo mặc định.5.4.3 Thuộc tính tính toán
Các thuộc tính được tính toán chỉ có thể được sử dụng trong các lớp khi thuộc tính là biểu tượng. Các thuộc tính theo kiểu Dict [nghĩa là, được trích dẫn hoặc tính toán các khóa không symbol, như được định nghĩa trong ??] không được phép. Một phương thức
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
63 nên được xác định cho bất kỳ lớp nào có thể lặp lại một cách logic. Ngoài ra, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
85 nên được sử dụng một cách tiết kiệm.Mẹo: Hãy cẩn thận khi sử dụng bất kỳ ký hiệu tích hợp nào khác [ví dụ:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
86] vì chúng không được trình biên dịch polyful và do đó sẽ không hoạt động trong các trình duyệt cũ hơn.5.4.4 Phương pháp tĩnh
Trong trường hợp nó không can thiệp vào khả năng đọc, thích các hàm mô-đun-local hơn các phương thức tĩnh riêng tư.
Các phương pháp tĩnh chỉ nên được gọi trên lớp cơ sở. Không nên gọi các phương thức tĩnh trên các biến chứa một thể hiện động có thể là hàm tạo hoặc hàm tạo phân lớp [và phải được xác định bằng
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
87 nếu điều này được thực hiện] và không được gọi trực tiếp trên một lớp con không xác định phương pháp tự nó.Disallowed:
/** @const */
exports = {exportedFunction};
35.4.5 Tuyên bố lớp cũ
Mặc dù các lớp ES6 được ưa thích, có những trường hợp các lớp ES6 có thể không khả thi. Ví dụ:
Nếu có hoặc sẽ tồn tại các lớp con, bao gồm các khung tạo ra các lớp con, điều đó không thể được thay đổi ngay lập tức để sử dụng cú pháp lớp ES6. Nếu một lớp như vậy sử dụng cú pháp ES6, tất cả các lớp con hạ lưu không sử dụng cú pháp lớp ES6 sẽ cần phải được sửa đổi.
Các khung yêu cầu giá trị
66 đã biết trước khi gọi hàm tạo siêu lớp, vì các hàm tạo có các lớp ES6 không có quyền truy cập vào giá trịgoog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
66 cho đến khi cuộc gọi đếngoog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
02 trả về.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
Theo tất cả các cách khác, hướng dẫn kiểu vẫn áp dụng cho mã này:
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
34, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33, các tham số mặc định, phần còn lại và các hàm mũi tên nên được sử dụng khi thích hợp.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
93 cho phép định nghĩa giống như lớp tương tự như cú pháp lớp ES6:/** @const */
exports = {exportedFunction};
4Ngoài ra, trong khi
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
93 nên được ưu tiên cho tất cả các mã mới, cú pháp truyền thống hơn cũng được cho phép./** @const */
exports = {exportedFunction};
5Các thuộc tính trên mỗi-nên được xác định trong hàm tạo sau khi gọi đến hàm tạo siêu lớp, nếu có một siêu lớp. Các phương pháp nên được xác định trên nguyên mẫu của hàm tạo.
Xác định hệ thống phân cấp nguyên mẫu xây dựng chính xác là khó hơn so với lần đầu tiên xuất hiện! Vì lý do đó, tốt nhất là sử dụng
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
95 từ thư viện đóng cửa.5.4.6 Không thao túng goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
81s trực tiếp
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
Từ khóa
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
97 cho phép các định nghĩa lớp rõ ràng và dễ đọc hơn so với việc xác định các thuộc tính goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
81. Mã thực hiện thông thường không có doanh nghiệp thao túng các đối tượng này, mặc dù chúng vẫn hữu ích cho việc xác định các lớp như được định nghĩa trong ??. Mixin và sửa đổi các nguyên mẫu của các đối tượng tích hợp bị cấm rõ ràng.Ngoại lệ: Mã khung [như polymer, hoặc góc] có thể cần sử dụng
81 và không nên dùng đến các cách giải quyết thậm chí để tránh làm như vậy.: Framework code [such as Polymer, or Angular] may need to use goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
81s, and should not resort to even-worse workarounds to avoid doing so.5.4.7 Getters and Setters
Không sử dụng các thuộc tính của JavaScript Getter và Setter. Họ có khả năng gây ngạc nhiên và khó khăn để lý luận, và có sự hỗ trợ hạn chế trong trình biên dịch. Cung cấp các phương pháp thông thường thay thế.
Ngoại lệ: Có những tình huống xác định một getter hoặc setter là không thể tránh khỏi [ví dụ: các khung liên kết dữ liệu như góc và polymer hoặc để tương thích với API bên ngoài không thể điều chỉnh]. Trong những trường hợp này, chỉ có thể sử dụng một cách thận trọng, với điều kiện chúng được xác định với các từ khóa phương thức tốc ký
00 và goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
01 hoặc goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
02 [không phải goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
03, cản trở việc đổi tên tài sản]. Getters không được thay đổi trạng thái quan sát được.: there are situations where defining a getter or setter is unavoidable [e.g. data binding frameworks such as Angular and Polymer, or for compatibility
with external APIs that cannot be adjusted]. In these cases only, getters and setters may be used with caution, provided they are defined with the goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
00 and goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
01 shorthand method keywords or goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
02 [not goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
03, which interferes with property renaming]. Getters must not change observable state.Disallowed:
/** @const */
exports = {exportedFunction};
65.4.8 Ghi đè toString
Phương pháp
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
04 có thể bị ghi đè, nhưng phải luôn thành công và không bao giờ có tác dụng phụ có thể nhìn thấy.Mẹo: Đặc biệt, hãy cẩn thận khi gọi các phương pháp khác từ toString, vì các điều kiện đặc biệt có thể dẫn đến các vòng lặp vô hạn.
5.4.9 Giao diện
Các giao diện có thể được khai báo với
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
05 hoặc goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
06. Các giao diện được khai báo với goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
06 có thể được rõ ràng [nghĩa là thông qua goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
08] hoặc được thực hiện ngầm bởi một lớp hoặc đối tượng theo nghĩa đen.Tất cả các thân phương thức không tĩnh trên giao diện phải là các khối trống. Các trường phải được tuyên bố là thành viên không được hưởng trong hàm tạo lớp.
Example:
/** @const */
exports = {exportedFunction};
75.4.10 Các lớp trừu tượng
Sử dụng các lớp trừu tượng khi thích hợp. Các lớp và phương pháp trừu tượng phải được chú thích bằng
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
09. Không sử dụng goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
10. Xem các lớp và phương pháp trừu tượng.5,5 chức năng
5.5.1 Chức năng cấp cao nhất
Các chức năng cấp cao nhất có thể được xác định trực tiếp trên đối tượng
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
92, hoặc nếu không được khai báo cục bộ và tùy chọn xuất khẩu. Nhìn thấy ?? Để biết thêm về xuất khẩu.Examples:
/** @const */
exports = {exportedFunction};
8/** @const */
exports = {exportedFunction};
95.5.2 Chức năng và đóng cửa lồng nhau
Các chức năng có thể chứa các định nghĩa chức năng lồng nhau. Nếu nó hữu ích để đặt cho chức năng một tên, nó nên được gán cho một
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33 cục bộ.5.5.3 Hàm mũi tên
Các hàm mũi tên cung cấp một cú pháp chức năng ngắn gọn và đơn giản hóa phạm vi
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66 cho các chức năng lồng nhau. Thích các hàm mũi tên hơn từ khóa goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
01, đặc biệt là cho các chức năng lồng nhau [nhưng xem ??].Thích các hàm mũi tên hơn các phương pháp phạm vi
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66 khác như goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
16, goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
17 và goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
18. Các hàm mũi tên đặc biệt hữu ích để gọi vào các cuộc gọi lại khi chúng cho phép chỉ định rõ ràng các tham số nào sẽ chuyển đến cuộc gọi lại trong khi ràng buộc sẽ chuyển qua tất cả các tham số.Phía bên trái của mũi tên chứa số không hoặc nhiều tham số. Điểm dừng xung quanh các tham số là tùy chọn nếu chỉ có một tham số không phá hủy duy nhất. Khi dấu ngoặc đơn được sử dụng, các loại tham số nội tuyến có thể được chỉ định [xem ??].
Mẹo: Luôn sử dụng dấu ngoặc đơn ngay cả đối với các hàm mũi tên đơn có thể tránh các tình huống trong đó thêm các tham số, nhưng quên thêm dấu ngoặc đơn, có thể dẫn đến mã có thể phân tích được không còn hoạt động như dự định.
Phía bên phải của mũi tên chứa phần thân của chức năng. Theo mặc định, cơ thể là một câu lệnh khối [0 hoặc nhiều câu lệnh được bao quanh bởi niềng răng xoăn]. Cơ thể cũng có thể là một biểu thức đơn được trả về ngầm nếu một trong hai: logic chương trình yêu cầu trả về một giá trị hoặc toán tử
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
20 đi trước một chức năng hoặc lệnh gọi phương thức [sử dụng goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
20 đảm bảo goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
45 được trả về, ngăn chặn các giá trị rò rỉ và truyền đạt ý định]. Mẫu biểu thức đơn được ưa thích nếu nó cải thiện khả năng đọc [ví dụ: đối với các biểu thức ngắn hoặc đơn giản].Examples:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
0Disallowed:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
15.5.4 Máy phát điện
Máy phát điện cho phép một số trừu tượng hữu ích và có thể được sử dụng khi cần thiết.
Khi xác định các chức năng của Trình tạo, hãy gắn
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
31 vào từ khóa goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
01 khi có mặt và tách nó ra với một khoảng trống khỏi tên của hàm. Khi sử dụng năng suất ủy quyền, hãy đính kèm từ khóa goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
26.Example:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
25.5.5 Tham số và các loại trả về
Các tham số chức năng và các loại trả về thường nên được ghi lại với các chú thích JSDOC. Nhìn thấy ?? để biết thêm thông tin.
5.5.5.1 Tham số mặc địnhCác tham số tùy chọn được cho phép bằng toán tử bằng trong danh sách tham số. Các tham số tùy chọn phải bao gồm các khoảng trống ở cả hai bên của toán tử bằng, được đặt tên chính xác giống như các tham số cần thiết [nghĩa là, không có tiền tố với
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
26], sử dụng hậu tố goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
27 trong loại JSDOC của chúng, đến sau các tham số cần thiết và không sử dụng các bộ khởi tạo có thể tạo các hiệu ứng. Tất cả các tham số tùy chọn cho các hàm cụ thể phải có giá trị mặc định, ngay cả khi giá trị đó là goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
45. Trái ngược với các hàm cụ thể, các phương thức trừu tượng và giao diện phải bỏ qua các giá trị tham số mặc định.Example:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
3Sử dụng tham số mặc định một cách tiết kiệm. Thích phá hủy [như trong ??] để tạo API có thể đọc được khi có nhiều hơn một số ít các tham số tùy chọn không có thứ tự tự nhiên.
Lưu ý: Không giống như các tham số mặc định của Python, việc sử dụng các bộ khởi tạo trả lại các đối tượng có thể thay đổi mới [chẳng hạn như
goog.module['search.urlHistory.UrlHistoryService'];
81 hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
52] vì trình khởi tạo được đánh giá mỗi khi giá trị mặc định được sử dụng, do đó, một đối tượng sẽ không được chia sẻ qua các cuộc gọi.Mẹo: Mặc dù các biểu thức tùy ý bao gồm các cuộc gọi chức năng có thể được sử dụng làm bộ khởi tạo, chúng nên được giữ đơn giản nhất có thể. Tránh các bộ khởi tạo hiển thị trạng thái có thể thay đổi được chia sẻ, vì điều đó có thể dễ dàng giới thiệu khớp nối ngoài ý muốn giữa các cuộc gọi chức năng.
5.5.5.2 Tham số RESTSử dụng tham số REST thay vì truy cập
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
31. Các tham số REST được gõ bằng tiền tố goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
51 trong JSDOC của họ. Tham số còn lại phải là tham số cuối cùng trong danh sách. Không có khoảng trống giữa goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
51 và tên tham số. Không đặt tên cho tham số REST goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
34. Không bao giờ đặt tên cho một biến cục bộ hoặc tham số goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
31, trong đó khó hiểu trong tên tích hợp.Example:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
45.5.6 Generics
Khai báo các hàm và phương pháp chung khi cần thiết với
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
36 trong JSDOC trên hàm hoặc định nghĩa phương thức.5.5.7 Toán tử lây lan
Các cuộc gọi chức năng có thể sử dụng toán tử lây lan [
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
51]. Thích toán tử lây lan hơn goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
38 khi một mảng hoặc có thể được giải nén thành nhiều tham số của hàm biến đổi. Không có không gian sau goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
51.Example:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
55.6 Chuỗi chữ
5.6.1 Sử dụng các báo giá đơn lẻ
Các chuỗi chuỗi thông thường được phân định bằng các trích dẫn đơn [
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
40], thay vì trích dẫn kép [goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
41].Mẹo: Nếu một chuỗi chứa một ký tự trích dẫn duy nhất, hãy xem xét sử dụng chuỗi mẫu để tránh phải thoát khỏi báo giá.
Chuỗi thông thường có thể không bao gồm nhiều dòng.
5.6.2 Mẫu theo nghĩa đen
Sử dụng các chữ cái mẫu [được phân định với
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
42] trong quá trình nối chuỗi phức tạp, đặc biệt nếu có nhiều chữ viết có liên quan. Mẫu chữ có thể trải dài nhiều dòng.Nếu một mẫu theo nghĩa đen kéo dài nhiều dòng, nó không cần phải tuân theo sự thụt của khối bao quanh, mặc dù có thể nếu khoảng trắng thêm không quan trọng.
Example:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
65.6.3 Không tiếp tục dòng
Không sử dụng các tiếp tục dòng [nghĩa là kết thúc một dòng bên trong một chuỗi theo nghĩa đen với một dấu gạch chéo ngược] trong các chữ viết thông thường hoặc mẫu. Mặc dù ES5 cho phép điều này, nhưng nó có thể dẫn đến các lỗi khó khăn nếu bất kỳ khoảng trắng nào xảy ra sau khi chém, và ít rõ ràng hơn đối với độc giả.
Disallowed:
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
7Thay vào đó, hãy viết
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
85,7 chữ số
Số có thể được chỉ định trong thập phân, hex, bát phân hoặc nhị phân. Sử dụng chính xác các tiền tố
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
43, goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
44 và goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
45, với các chữ cái viết thường, cho hex, octal và nhị phân, tương ứng. Không bao giờ bao gồm một số 0 hàng đầu trừ khi nó được theo sau bởi goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
46, goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
47 hoặc goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
48.5.8 Cấu trúc điều khiển
5.8.1 cho các vòng
Với ES6, ngôn ngữ hiện có ba loại vòng
goog.module['search.urlHistory.UrlHistoryService'];
75 khác nhau. Tất cả có thể được sử dụng, mặc dù ____ ____ 275 -____ 325 vòng lặp nên được ưu tiên khi có thể.________ 275 -________ 324 Vòng chỉ có thể được sử dụng trên các đối tượng theo kiểu Dict [xem ??], và không nên được sử dụng để lặp lại trên một mảng.
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
54 nên được sử dụng trong ________ 275 -________ 324 vòng để loại trừ các thuộc tính nguyên mẫu không mong muốn. Thích ________ 275 -________ 325 và goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
59 hơn ________ 275 -____ 324 khi có thể.5.8.2 ngoại lệ
Ngoại lệ là một phần quan trọng của ngôn ngữ và nên được sử dụng bất cứ khi nào các trường hợp đặc biệt xảy ra. Luôn ném
goog.module['search.urlHistory.UrlHistoryService'];
63S hoặc các lớp con của goog.module['search.urlHistory.UrlHistoryService'];
63: Không bao giờ ném chuỗi chữ hoặc các đối tượng khác. Luôn luôn sử dụng goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
64 khi xây dựng goog.module['search.urlHistory.UrlHistoryService'];
63.Điều trị này mở rộng đến các giá trị từ chối
goog.module['search.urlHistory.UrlHistoryService'];
65 là goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
67 tương đương với goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
68 trong các chức năng Async.Các ngoại lệ tùy chỉnh cung cấp một cách tuyệt vời để truyền tải thông tin lỗi bổ sung từ các chức năng. Chúng nên được xác định và sử dụng bất cứ nơi nào loại
goog.module['search.urlHistory.UrlHistoryService'];
63 bản địa là không đủ.Thích ném ngoại lệ hơn các phương pháp xử lý lỗi đặc biệt [chẳng hạn như truyền loại tham chiếu container lỗi hoặc trả về một đối tượng có thuộc tính lỗi].
5.8.2.1 Khối bắt trốngThật hiếm khi chính xác khi không làm gì để đáp ứng với một ngoại lệ bị bắt. Khi nó thực sự thích hợp để không có hành động nào trong một khối bắt, lý do điều này là hợp lý được giải thích trong một bình luận.
import './sideeffects.js';
import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';
import {name} from './sibling.js';
9Disallowed:
import '../directory/file';
0Mẹo: Không giống như trong một số ngôn ngữ khác, các mẫu như ở trên chỉ đơn giản là làm việc vì điều này sẽ bắt được lỗi do
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
70 ném. Sử dụng goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
71 thay thế.5.8.3 Câu lệnh chuyển đổi
Thuật ngữ Lưu ý: Bên trong niềng răng của một khối chuyển đổi là một hoặc nhiều nhóm câu lệnh. Mỗi nhóm câu lệnh bao gồm một hoặc nhiều nhãn chuyển đổi [
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
72 hoặc goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
73], theo sau là một hoặc nhiều câu lệnh.5.8.3.1 Fall-the Fall: Nhận xétTrong một khối chuyển đổi, mỗi nhóm câu lệnh sẽ chấm dứt đột ngột [với ngoại lệ
goog.module['search.urlHistory.UrlHistoryService'];
89, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
21 hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
22N] hoặc được đánh dấu bằng nhận xét để chỉ ra rằng việc thực thi sẽ hoặc có thể tiếp tục vào nhóm câu lệnh tiếp theo. Bất kỳ nhận xét nào truyền đạt ý tưởng về sự sụp đổ là đủ [thường là goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
77]. Nhận xét đặc biệt này là không bắt buộc trong nhóm tuyên bố cuối cùng của khối chuyển đổi.Example:
import '../directory/file';
15.8.3.2 Trường hợp goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
78 có mặtMỗi câu lệnh Switch bao gồm một nhóm câu lệnh
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
78, ngay cả khi nó không chứa mã. Nhóm tuyên bố goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
78 phải là cuối cùng.5.9 này
Chỉ sử dụng
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66 trong các hàm tạo và phương thức lớp, trong các hàm mũi tên được xác định trong các hàm tạo và phương thức lớp, hoặc trong các chức năng có goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
82 rõ ràng được khai báo trong chức năng bao gồm ngay lập tức.Không bao giờ sử dụng
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66 để chỉ đối tượng toàn cầu, bối cảnh của goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
84, mục tiêu của một sự kiện hoặc các hàm goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
85ED hoặc goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
86 không cần thiết.5.10 Kiểm tra bình đẳng
Sử dụng toán tử nhận dạng [________ 487/________ 488] ngoại trừ trong các trường hợp được ghi lại dưới đây.
5.10.1 Các trường hợp ngoại lệ trong đó sự ép buộc là mong muốn
Bắt cả hai giá trị
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
89 và goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
45:import '../directory/file';
25.11 Các tính năng không được phép
5.11.1 với
Không sử dụng từ khóa
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
91. Nó làm cho mã của bạn khó hiểu hơn và đã bị cấm ở chế độ nghiêm ngặt kể từ ES5.5.11.2 Đánh giá mã động
Không sử dụng hàm tạo
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
84 hoặc goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
93 [ngoại trừ trình tải mã]. Các tính năng này có khả năng nguy hiểm và đơn giản là không hoạt động trong môi trường CSP.5.11.3 Chèn dấu chấm phẩy tự động
Luôn chấm dứt các câu lệnh với dấu chấm phẩy [ngoại trừ chức năng và khai báo lớp, như đã lưu ý ở trên].
5.11.4 Các tính năng không chuẩn
Không sử dụng các tính năng không chuẩn. Điều này bao gồm các tính năng cũ đã bị xóa [ví dụ:
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
94], các tính năng mới chưa được tiêu chuẩn hóa [ví dụ: bản nháp làm việc TC39 hiện tại, các đề xuất ở bất kỳ giai đoạn nào hoặc các tiêu chuẩn web được đề xuất nhưng chưa hoàn thành] hoặc các tính năng độc quyền chỉ được thực hiện trong một số trình duyệt. Chỉ sử dụng các tính năng được xác định trong các tiêu chuẩn ECMA-262 hoặc WhatWG hiện tại. . Ngôn ngữ phi tiêu chuẩn Các phần mở rộng của người Viking [chẳng hạn như những người được cung cấp bởi một số người chuyển đổi bên ngoài] bị cấm.5.11.5 Đối tượng bao bọc cho các loại nguyên thủy
Không bao giờ sử dụng
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
64 trên các trình bao bọc đối tượng nguyên thủy [goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
96, goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
97, goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
98, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
85], cũng không bao gồm chúng trong các chú thích loại.Disallowed:
import '../directory/file';
3Các gói có thể được gọi là chức năng ép buộc [được ưu tiên hơn bằng cách sử dụng
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
00 hoặc nối chuỗi trống] hoặc tạo các ký hiệu.Example:
import '../directory/file';
45.11.6 Sửa đổi các đối tượng tích hợp
Không bao giờ sửa đổi các loại tích hợp, bằng cách thêm các phương thức vào các hàm tạo của chúng hoặc vào các nguyên mẫu của chúng. Tránh tùy thuộc vào các thư viện làm điều này. Lưu ý rằng thư viện thời gian chạy JSCompiler sẽ cung cấp các polyfills tuân thủ tiêu chuẩn nếu có thể; Không có gì khác có thể sửa đổi các đối tượng tích hợp.
Không thêm các ký hiệu vào đối tượng toàn cầu trừ khi thực sự cần thiết [ví dụ: yêu cầu của API của bên thứ ba].
5.11.7 Bỏ qua const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
01 khi gọi một hàm tạo
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
Không bao giờ gọi một hàm tạo trong một câu lệnh
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
64 mà không sử dụng dấu ngoặc đơn const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
01.Disallowed:
import '../directory/file';
5Sử dụng thay thế:
import '../directory/file';
6Bỏ qua dấu ngoặc đơn có thể dẫn đến những sai lầm tinh tế. Hai dòng này không tương đương:
import '../directory/file';
76 Đặt tên
6.1 Quy tắc chung cho tất cả các định danh
Số nhận dạng chỉ sử dụng các chữ cái và chữ số ASCII, và, trong một số ít các trường hợp được ghi nhận dưới đây, nhấn mạnh và rất hiếm khi [khi được yêu cầu bởi các khung như Angular] Dollar Dấu hiệu.
Đặt theo mô tả một tên càng tốt, trong lý do. Đừng lo lắng về việc tiết kiệm không gian ngang vì điều quan trọng hơn là làm cho mã của bạn có thể hiểu được ngay lập tức bởi một người đọc mới. Không sử dụng các chữ viết tắt không rõ ràng hoặc không quen thuộc với độc giả bên ngoài dự án của bạn và không viết tắt bằng cách xóa các chữ cái trong một từ.
import '../directory/file';
8Disallowed:
import '../directory/file';
96.2 Quy tắc theo loại định danh
6.2.1 Tên gói
Tên gói đều là
goog.module['search.urlHistory.UrlHistoryService'];
01. Ví dụ: const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
05, nhưng không phải const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
06 hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
07.6.2.2 Tên lớp
Tên lớp, giao diện, bản ghi và tên typedef được viết bằng
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
08. Các lớp không được đề cập chỉ đơn giản là người dân địa phương: chúng không được đánh dấu /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 và do đó không được đặt tên với một dấu gạch dưới.Tên loại thường là danh từ hoặc cụm danh từ. Ví dụ:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
10, const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
11 hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
12. Ngoài ra, tên giao diện đôi khi có thể là tính từ hoặc cụm từ tính từ thay thế [ví dụ: const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
13].6.2.3 Tên phương thức
Tên phương thức được viết trong
goog.module['search.urlHistory.UrlHistoryService'];
01. Tên cho các phương pháp /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 phải kết thúc bằng dấu gạch dưới.Tên phương thức thường là động từ hoặc cụm động từ. Ví dụ:
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
16 hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
17. Các phương thức getter và setter cho các thuộc tính không bao giờ được yêu cầu, nhưng nếu chúng được sử dụng, chúng nên được đặt tên là const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
18 [hoặc tùy chọn const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
19 hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
20 cho booleans] hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
21 cho setters.Dấu gạch dưới cũng có thể xuất hiện trong tên phương thức thử nghiệm JSunit để tách các thành phần logic của tên. Một mẫu điển hình là
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
22, ví dụ const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
23. Không có một cách chính xác để đặt tên cho các phương thức kiểm tra.6.2.4 Tên enum
Tên enum được viết bằng
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
08, tương tự như các lớp và thường là danh từ số ít. Các mục riêng lẻ trong enum được đặt tên trong const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
25.6.2.5 Tên không đổi
Tên không đổi Sử dụng
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
25: Tất cả các chữ cái chữ hoa, với các từ được phân tách bằng dấu gạch dưới. Không có lý do gì để một hằng số được đặt tên với một dấu gạch dưới, vì các thuộc tính tĩnh riêng có thể được thay thế bằng mô -đun [hoàn toàn riêng tư] Người dân địa phương.6.2.5.1 Định nghĩa về "hằng số"Mỗi hằng số là một thuộc tính tĩnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96 hoặc khai báo mô-đun goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33, nhưng không phải tất cả các thuộc tính tĩnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96 và mô-đun-local goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33 là hằng số. Trước khi chọn trường hợp liên tục, hãy xem xét liệu lĩnh vực này có thực sự cảm thấy như một hằng số bất biến sâu sắc hay không. Ví dụ, nếu bất kỳ trạng thái quan sát nào của trường hợp đó có thể thay đổi, thì nó gần như chắc chắn không phải là hằng số. Chỉ có ý định không bao giờ đột biến đối tượng nói chung là không đủ.Examples:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
00Các tên hằng số thường là danh từ hoặc cụm danh từ.
6.2.5.2 Bí danh địa phươngBí danh địa phương nên được sử dụng bất cứ khi nào chúng cải thiện khả năng đọc so với các tên đủ điều kiện đầy đủ. Thực hiện theo các quy tắc tương tự như
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74s [??], duy trì phần cuối cùng của tên bí danh. Bí danh cũng có thể được sử dụng trong các chức năng. Bí danh phải là goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33.Examples:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
016.2.6 Tên trường không liên tục
Tên trường không liên tục [tĩnh hoặc khác] được viết vào
goog.module['search.urlHistory.UrlHistoryService'];
01, với một dấu gạch dưới cho các trường tư nhân.Những tên này thường là danh từ hoặc cụm danh từ. Ví dụ,
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
34 hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
35.6.2.7 Tên tham số
Tên tham số được viết trong
goog.module['search.urlHistory.UrlHistoryService'];
01. Lưu ý rằng điều này áp dụng ngay cả khi tham số mong đợi một hàm tạo.Tên tham số một ký tự không nên được sử dụng trong các phương thức công khai.
Ngoại lệ: Khi được yêu cầu bởi khung của bên thứ ba, tên tham số có thể bắt đầu bằng
37. Ngoại lệ này không áp dụng cho bất kỳ định danh nào khác [ví dụ: các biến hoặc thuộc tính cục bộ].:
When required by a third-party framework, parameter names may begin with a const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
37. This exception does not apply to any other identifiers [e.g. local variables or properties].6.2.8 Tên biến cục bộ
Tên biến cục bộ được viết trong
goog.module['search.urlHistory.UrlHistoryService'];
01, ngoại trừ các hằng số mô-đun-local [cấp cao nhất], như được mô tả ở trên. Các hằng số trong phạm vi chức năng vẫn được đặt tên trong goog.module['search.urlHistory.UrlHistoryService'];
01. Lưu ý rằng goog.module['search.urlHistory.UrlHistoryService'];
01 được sử dụng ngay cả khi biến chứa hàm tạo.6.2.9 Tên tham số mẫu
Tên tham số mẫu phải súc tích, định danh một chữ cái hoặc một chữ cái và phải là tất cả các nắp, chẳng hạn như
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
41 hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
42.6.2.10 Tên mô-đun địa phương
Các tên mô-đun-địa phương không được xuất khẩu là hoàn toàn riêng tư. Chúng không được đánh dấu
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 và không kết thúc trong một dấu gạch dưới. Điều này áp dụng cho các lớp, hàm, biến, hằng số, enum và các định danh mô-đun địa phương khác.6.3 Trường hợp lạc đà: được xác định
Đôi khi có nhiều hơn một cách hợp lý để chuyển đổi một cụm từ tiếng Anh thành trường hợp lạc đà, chẳng hạn như khi các từ viết tắt hoặc các cấu trúc bất thường như IPv6 hoặc iOS có mặt. Để cải thiện khả năng dự đoán, Google Style chỉ định sơ đồ xác định [gần như] sau đây.
Bắt đầu với hình thức văn xuôi của tên:
- Chuyển đổi cụm từ thành ASCII đơn giản và loại bỏ bất kỳ dấu nháy đơn nào. Ví dụ, thuật toán của Müller có thể trở thành thuật toán Mueller.
- Chia kết quả này thành các từ, phân tách trên khoảng trống và bất kỳ dấu câu còn lại [thường là dấu gạch nối].
- Được đề xuất: Nếu bất kỳ từ nào đã có một trường hợp lạc đà thông thường xuất hiện trong cách sử dụng chung, hãy chia điều này thành các phần cấu thành của nó [ví dụ: AdWords trở thành từ AD]. Lưu ý rằng một từ như iOS không thực sự trong trường hợp lạc đà mỗi se; Nó bất chấp bất kỳ quy ước, vì vậy khuyến nghị này không được áp dụng.
- Bây giờ viết thường mọi thứ [bao gồm cả từ viết tắt], sau đó chỉ có ký tự đầu tiên của:
- Mỗi từ, để mang lại trường hợp lạc đà phía trên, hoặc
- Mỗi từ ngoại trừ từ đầu tiên, để mang lại hộp lạc đà thấp hơn
- Cuối cùng, tham gia tất cả các từ vào một định danh duy nhất.
Lưu ý rằng vỏ của các từ gốc gần như hoàn toàn coi thường.
Examples:
Yêu cầu XML HTTP | Xmlhttprequest | Xmlhttprequest |
ID khách hàng mới | Newcustomerid | Newcustomerid |
Đồng hồ bấm giờ bên trong | InnStopWatch | InnStopWatch |
Hỗ trợ IPv6 trên iOS? | Hỗ trợsipv6onios | Hỗ trợsipv6onios |
Nhà nhập khẩu YouTube | YouTubeImporter | YouTubeImporter* |
*Có thể chấp nhận, nhưng không được khuyến nghị.
Lưu ý: Một số từ bị gạch nối mơ hồ trong ngôn ngữ tiếng Anh: ví dụ: không bình thường và không trống đều chính xác, vì vậy tên phương thức CheckNonempty và CheckNonempty đều đúng.
7 JSDOC
JSDOC được sử dụng trên tất cả các lớp, trường và phương thức.
7.1 Mẫu chung
Định dạng cơ bản của các khối JSDOC được thấy trong ví dụ này:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
02hoặc trong ví dụ một dòng này:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
03Nếu một nhận xét một dòng tràn vào nhiều dòng, nó phải sử dụng kiểu đa dòng với
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
44 và const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
45 trên các dòng của riêng họ.Nhiều công cụ trích xuất siêu dữ liệu từ các bình luận của JSDOC để thực hiện xác thực và tối ưu hóa mã. Như vậy, những ý kiến này phải được hình thành tốt.must be well-formed.
7.2 Markdown
JSDOC được viết bằng Markdown, mặc dù nó có thể bao gồm HTML khi cần thiết.
Lưu ý rằng các công cụ tự động trích xuất JSDOC [ví dụ: Jsdossier] thường sẽ bỏ qua định dạng văn bản đơn giản, vì vậy nếu bạn đã làm điều này:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
04Nó sẽ ra như thế này:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
05Thay vào đó, hãy viết một danh sách đánh dấu:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
067.3 Thẻ JSDOC
Google Style cho phép một tập hợp con của các thẻ JSDOC. Nhìn thấy ?? cho danh sách đầy đủ. Hầu hết các thẻ phải chiếm dòng riêng của chúng, với thẻ ở đầu dòng.
Disallowed:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
07Các thẻ đơn giản không yêu cầu bất kỳ dữ liệu bổ sung nào [chẳng hạn như
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96, const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
48, const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
49] có thể được kết hợp trên cùng một dòng, cùng với một loại tùy chọn khi thích hợp./* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
08Không có quy tắc khó cho khi nào nên kết hợp các thẻ, hoặc theo thứ tự nào, nhưng phải nhất quán.
Để biết thông tin chung về các loại chú thích trong JavaScript, hãy xem chú thích JavaScript cho trình biên dịch đóng và các loại trong hệ thống loại đóng.
7,4 Line Gói
Thẻ khối được bọc dòng được thụt vào bốn không gian. Văn bản mô tả được bọc có thể được xếp hàng với mô tả trên các dòng trước, nhưng sự liên kết ngang này không được khuyến khích.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
09Không thụt vào khi gói mô tả
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
50 hoặc /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
70.Một tập tin có thể có tổng quan về tệp cấp cao nhất. Thông báo bản quyền, thông tin tác giả và mức độ hiển thị mặc định là tùy chọn. Tổng quan về tệp thường được đề xuất bất cứ khi nào một tệp bao gồm nhiều hơn một định nghĩa lớp. Nhận xét cấp cao nhất được thiết kế để định hướng độc giả không quen thuộc với mã theo những gì trong tệp này. Nếu có, nó có thể cung cấp mô tả về nội dung của tệp và bất kỳ phụ thuộc hoặc thông tin tương thích nào. Các dòng được bọc không được thụt vào.
Example:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
10Các lớp, giao diện và bản ghi phải được ghi lại với mô tả và bất kỳ tham số mẫu nào, giao diện được triển khai, khả năng hiển thị hoặc các thẻ thích hợp khác. Mô tả lớp sẽ cung cấp cho người đọc đủ thông tin để biết cách thức và thời điểm sử dụng lớp, cũng như bất kỳ cân nhắc bổ sung nào cần thiết để sử dụng chính xác lớp. Mô tả văn bản có thể được bỏ qua trên hàm tạo. Các chú thích
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
52 và goog.module['search.urlHistory.UrlHistoryService'];
88 không được sử dụng với từ khóa goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
97 trừ khi lớp được sử dụng để khai báo goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
05 hoặc mở rộng một lớp chung./* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
117.7 Nhận xét về Enum và typedef
Tất cả các enum và typedefs phải được ghi lại bằng các thẻ JSDOC thích hợp [
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
56 hoặc goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
73] trên dòng trước. Enums và typedefs công khai cũng phải có một mô tả. Các mục enum cá nhân có thể được ghi lại với nhận xét JSDOC về dòng trước./* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
12Typedefs rất hữu ích để xác định các loại bản ghi ngắn hoặc bí danh cho các công đoàn, chức năng phức tạp hoặc các loại chung. Nên tránh đánh máy cho các loại hồ sơ với nhiều trường, vì chúng không cho phép ghi lại các trường riêng lẻ, cũng như không sử dụng các mẫu hoặc tham chiếu đệ quy. Đối với các loại hồ sơ lớn, thích
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
06.7.8 Phương pháp và nhận xét chức năng
Trong các phương thức và các hàm được đặt tên, tham số và loại trả về phải được ghi lại, ngoại trừ trong trường hợp có cùng chữ ký
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
59S, trong đó tất cả các loại bị bỏ qua. Loại goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
66 nên được ghi lại khi cần thiết. Loại trả về có thể bị bỏ qua nếu hàm không có câu lệnh goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
21 không trống.
Phương thức, tham số và mô tả trả về [nhưng không phải loại] có thể bị bỏ qua nếu chúng rõ ràng từ phần còn lại của phương thức JSDOC hoặc từ chữ ký của nó.
Mô tả phương thức bắt đầu bằng một cụm động từ mô tả những gì phương thức làm. Cụm từ này không phải là một câu bắt buộc, mà thay vào đó được viết ở người thứ ba, như thể có một phương pháp này ngụ ý ... trước nó.
Nếu một phương thức ghi đè một phương thức siêu lớp, nó phải bao gồm một chú thích
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
59. Các phương thức ghi đè kế thừa tất cả các chú thích JSDOC từ phương thức siêu lớp [bao gồm các chú thích khả năng hiển thị] và chúng nên được bỏ qua trong phương thức ghi đè. Tuy nhiên, nếu bất kỳ loại nào được tinh chỉnh trong các chú thích loại, tất cả các chú thích const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
63 và const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
64 phải được chỉ định rõ ràng./* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
13Nếu bạn chỉ cần ghi lại các loại tham số và trả về của một hàm, bạn có thể tùy ý sử dụng JSDOCs nội tuyến trong chữ ký của hàm. Các JSDocs nội tuyến này chỉ định các loại trả về và các loại param mà không có thẻ.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
14Nếu bạn cần mô tả hoặc thẻ, hãy sử dụng một nhận xét JSDOC duy nhất ở trên phương thức. Ví dụ: các phương thức trả về giá trị cần thẻ
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
64./* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
15/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
16Trong các chú thích chức năng ẩn danh thường là tùy chọn. Nếu suy luận loại tự động không đủ hoặc chú thích rõ ràng sẽ cải thiện khả năng đọc, thì hãy chú thích các loại tham số và trả về như thế này:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
17Đối với biểu thức loại chức năng, xem ??.
Các loại tài sản phải được ghi lại. Mô tả có thể được bỏ qua cho các thuộc tính riêng tư, nếu tên và loại cung cấp đủ tài liệu để hiểu mã.
Các hằng số xuất khẩu công khai được bình luận giống như các thuộc tính.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
187.10 Loại chú thích
Các chú thích loại được tìm thấy trên
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
63, const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
64, goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
82 và const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
69 và tùy chọn trên /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96, const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
49 và bất kỳ thẻ khả năng hiển thị nào. Loại chú thích gắn liền với các thẻ JSDOC phải luôn được đặt trong niềng răng.7.10.1 Khả năng vô hiệu
Hệ thống loại xác định các sửa đổi
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
72 và const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
73 cho không có null và nullable, tương ứng. Những sửa đổi này phải đi trước loại.Bộ điều chỉnh khả năng vô hiệu hóa có các yêu cầu khác nhau cho các loại khác nhau, thuộc hai loại rộng:
- Loại chú thích cho các nguyên thủy [
74,const /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
75,const /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
76,const /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
77,const /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
45,goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
89] và các chữ [goog.module['my.test.helpers']; goog.module.declareLegacyNamespace[]; goog.setTestOnly[];
80 vàconst /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
81] luôn không thể chấp nhận được theo mặc định. Sử dụng công cụ sửa đổiconst /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
73 để làm cho nó vô hiệu hóa, nhưng bỏ quaconst /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
72 dự phòng.const /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
- Các loại tham chiếu [nói chung, bất cứ điều gì trong
08, bao gồmconst /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
85] đề cập đến một lớp, enum, bản ghi hoặc typedef được xác định ở nơi khác. Vì các loại này có thể hoặc không thể vô hiệu hóa, nên không thể biết từ tên đó cho dù nó có thể không có được hay không. Luôn luôn sử dụng các sửa đổiconst /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
73 vàconst /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
72 rõ ràng cho các loại này để ngăn chặn sự mơ hồ tại các trang web sử dụng.const /** !Array */ exportedArray = [1, 2, 3]; const /** !Array */ moduleLocalArray = [4, 5, 6]; /** @return {number} */ function moduleLocalFunction[] { return moduleLocalArray.length; } /** @return {number} */ function exportedFunction[] { return moduleLocalFunction[] * 2; } exports = {exportedArray, exportedFunction};
Bad:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
19Good:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
207.10.2 loại đúc
Trong trường hợp trình biên dịch không suy ra chính xác loại biểu thức và các chức năng khẳng định trong goog.asserts không thể khắc phục nó, có thể thắt chặt loại bằng cách thêm nhận xét chú thích loại và đặt biểu thức trong ngoặc đơn. Lưu ý rằng dấu ngoặc đơn được yêu cầu.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
217.10.3 Các loại tham số mẫu
Luôn chỉ định tham số mẫu. Bằng cách này, trình biên dịch có thể làm một công việc tốt hơn và nó giúp người đọc dễ hiểu hơn về mã.
Bad:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
22Good:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
23Các trường hợp không nên sử dụng tham số mẫu: không nên sử dụng:
50 được sử dụng cho phân cấp loại và không như cấu trúc giống như bản đồ.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
7.10.4 Biểu thức loại chức năng
Thuật ngữ Lưu ý: Biểu thức loại chức năng đề cập đến một chú thích loại cho các loại chức năng với từ khóa
01 trong chú thích [xem ví dụ bên dưới].: function type expression refers to a type annotation for function types with the keyword goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
01 in the annotation [see examples below].Trong đó định nghĩa hàm được đưa ra, không sử dụng biểu thức loại chức năng. Chỉ định tham số và các loại trả về với
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
63 và const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
64 hoặc với các chú thích nội tuyến [xem ??]. Điều này bao gồm các hàm và hàm ẩn danh được xác định và gán cho một const [trong đó hàm JSDOC xuất hiện trên toàn bộ biểu thức gán].Các biểu thức loại chức năng là cần thiết, ví dụ, bên trong
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
56, const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
63 hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
64. Sử dụng nó cũng cho các biến hoặc thuộc tính của loại chức năng, nếu chúng không được khởi tạo ngay lập tức với định nghĩa hàm. /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
24Khi sử dụng biểu thức loại chức năng, luôn chỉ định loại trả về một cách rõ ràng. Mặt khác, loại trả lại mặc định không rõ [
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
73], dẫn đến hành vi kỳ lạ và bất ngờ, và hiếm khi những gì thực sự mong muốn.Xấu - loại lỗi, nhưng không có cảnh báo nào được đưa ra:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
25Good:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
267.10.5 Whitespace
Trong một chú thích loại, cần có một khoảng trống hoặc ngắt dòng sau mỗi dấu phẩy hoặc đại tràng. Các lần ngắt dòng bổ sung có thể được chèn để cải thiện khả năng đọc hoặc tránh vượt quá giới hạn cột. Những lần nghỉ này nên được chọn và thụt vào theo các hướng dẫn hiện hành [ví dụ: ?? và ??]. Không có khoảng trắng nào khác được phép trong các chú thích loại.
Good:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
27Bad:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
287.11 Chú thích khả năng hiển thị
Chú thích khả năng hiển thị [
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
79, goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
78] có thể được chỉ định trong khối /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
70 hoặc trên bất kỳ biểu tượng hoặc thuộc tính được xuất nào. Không chỉ định khả năng hiển thị cho các biến cục bộ, cho dù trong một hàm hoặc ở cấp cao nhất của mô -đun. Tất cả các tên /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 phải kết thúc với một dấu gạch dưới.8 chính sách
8.1 Các vấn đề không được xác định bởi Google Style: Hãy nhất quán!
Đối với bất kỳ câu hỏi phong cách nào không được giải quyết dứt khoát bởi đặc điểm kỹ thuật này, thích làm những gì mã khác trong cùng một tệp đã làm. Nếu điều đó không giải quyết được câu hỏi, hãy xem xét mô phỏng các tệp khác trong cùng một gói.
8.2 Cảnh báo trình biên dịch
8.2.1 Sử dụng bộ cảnh báo tiêu chuẩn
Càng xa các dự án có thể nên sử dụng
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
01.8.2.2 Cách xử lý cảnh báo
Trước khi làm bất cứ điều gì, hãy chắc chắn rằng bạn hiểu chính xác những gì cảnh báo đang nói với bạn. Nếu bạn không tích cực tại sao một cảnh báo xuất hiện, hãy yêu cầu giúp đỡ.
Khi bạn hiểu cảnh báo, hãy thử các giải pháp sau theo thứ tự:
- Đầu tiên, sửa nó hoặc làm việc xung quanh nó. Thực hiện một nỗ lực mạnh mẽ để thực sự giải quyết cảnh báo, hoặc tìm một cách khác để hoàn thành nhiệm vụ hoàn toàn tránh được tình huống. Make a strong attempt to actually address the warning, or find another way to accomplish the task that avoids the situation entirely.
- Nếu không, hãy xác định xem đó có phải là báo động sai hay không. Nếu bạn bị thuyết phục rằng cảnh báo là không hợp lệ và mã thực sự an toàn và chính xác, hãy thêm một nhận xét để thuyết phục người đọc về thực tế này và áp dụng chú thích
02. If you are convinced that the warning is invalid and that the code is actually safe and correct, add a comment to convince the reader of this fact and apply the/** @const {number} */ exports.CONSTANT_ONE = 1; /** @const {string} */ exports.CONSTANT_TWO = 'Another constant';
02 annotation./** @const {number} */ exports.CONSTANT_ONE = 1; /** @const {string} */ exports.CONSTANT_TWO = 'Another constant';
- Nếu không, để lại một bình luận todo. Đây là một phương sách cuối cùng. Nếu bạn làm điều này, đừng đàn áp cảnh báo. Cảnh báo nên được nhìn thấy cho đến khi nó có thể được chăm sóc đúng cách. This is a last resort. If you do this, do not suppress the warning. The warning should be visible until it can be taken care of properly.
8.2.3 Bị cảnh báo ở phạm vi hợp lý hẹp nhất
Các cảnh báo bị triệt tiêu ở phạm vi hợp lý hẹp nhất, thường là của một biến cục bộ hoặc phương pháp rất nhỏ. Thường thì một biến hoặc phương pháp được trích xuất chỉ vì lý do đó.
Thí dụ
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
29Ngay cả một số lượng lớn các đàn áp trong một lớp vẫn tốt hơn so với việc làm mờ toàn bộ lớp với loại cảnh báo này.
8.3 Khấu hao
Đánh dấu các phương thức, lớp hoặc giao diện không dùng nữa với các chú thích
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
03. Một bình luận không nhận được bao gồm các hướng đơn giản, rõ ràng để mọi người sửa chữa các trang web cuộc gọi của họ.8.4 Mã không theo kiểu Google
Thỉnh thoảng bạn sẽ gặp các tệp trong cơ sở mã không có phong cách Google thích hợp. Những điều này có thể đến từ việc mua lại, hoặc có thể đã được viết trước khi Google Style có một vị trí về một số vấn đề hoặc có thể theo phong cách không google vì bất kỳ lý do nào khác.
8.4.1 Định dạng lại mã hiện có
Khi cập nhật phong cách của mã hiện có, hãy làm theo các hướng dẫn này.
- Không bắt buộc phải thay đổi tất cả các mã hiện có để đáp ứng các hướng dẫn kiểu hiện tại. Định dạng lại mã hiện tại là sự đánh đổi giữa mã hóa và tính nhất quán. Các quy tắc phong cách phát triển theo thời gian và các loại điều chỉnh này để duy trì sự tuân thủ sẽ tạo ra sự khuấy động không cần thiết. Tuy nhiên, nếu những thay đổi đáng kể đang được thực hiện đối với một tệp, dự kiến rằng tệp sẽ theo kiểu Google.
- Hãy cẩn thận để không cho phép các sửa chữa phong cách cơ hội để xử lý sự tập trung của CL. Nếu bạn thấy mình thực hiện nhiều thay đổi về phong cách mà không quan trọng đối với trọng tâm của CL, hãy thúc đẩy những thay đổi đó thành một CL riêng biệt.
8.4.2 Mã mới được thêm vào: Sử dụng Google Style
Các tệp hoàn toàn mới sử dụng Google Style, bất kể lựa chọn kiểu của các tệp khác trong cùng một gói.
Khi thêm mã mới vào một tệp không có theo kiểu Google, việc định dạng lại mã hiện tại trước tiên được khuyến nghị, theo lời khuyên trong ??.
Nếu định dạng lại này không được thực hiện, thì mã mới sẽ nhất quán nhất có thể với mã hiện có trong cùng một tệp, nhưng không được vi phạm hướng dẫn kiểu.
8.5 Quy tắc phong cách địa phương
Các nhóm và dự án có thể áp dụng các quy tắc phong cách bổ sung ngoài các quy tắc trong tài liệu này, nhưng phải chấp nhận rằng các thay đổi dọn dẹp có thể không tuân thủ các quy tắc bổ sung này và không được chặn các thay đổi dọn dẹp đó do vi phạm bất kỳ quy tắc bổ sung nào. Cẩn thận với các quy tắc quá mức mà không có mục đích. Hướng dẫn phong cách không tìm cách xác định phong cách trong mọi kịch bản có thể và bạn cũng không nên.
8.6 Mã được tạo: Chủ yếu là được miễn trừ
Mã nguồn được tạo bởi quy trình xây dựng không bắt buộc phải theo kiểu Google. Tuy nhiên, bất kỳ định danh được tạo nào sẽ được tham chiếu từ mã nguồn viết tay phải tuân theo các yêu cầu đặt tên. Là một ngoại lệ đặc biệt, các định danh như vậy được phép chứa dấu gạch dưới, điều này có thể giúp tránh xung đột với các định danh viết tay.
9 Phụ lục
9.1 Tham khảo thẻ JSDOC
JSDOC phục vụ nhiều mục đích trong JavaScript. Ngoài việc được sử dụng để tạo tài liệu, nó cũng được sử dụng để kiểm soát dụng cụ. Được biết đến nhiều nhất là chú thích loại trình biên dịch đóng cửa.
9.1.1 Chú thích loại và các chú thích trình biên dịch đóng khác
Tài liệu cho JSDOC được sử dụng bởi trình biên dịch đóng được mô tả trong chú thích JavaScript cho trình biên dịch đóng và các loại trong hệ thống loại đóng.
9.1.2 Chú thích tài liệu
Ngoài JSDOC được mô tả trong chú thích JavaScript cho trình biên dịch đóng, các thẻ sau đây là phổ biến và được hỗ trợ tốt bởi các công cụ tạo tài liệu khác nhau [như JSDossier] cho mục đích tài liệu thuần túy.
Bạn cũng có thể thấy các loại chú thích JSDOC khác trong mã của bên thứ ba. Các chú thích này xuất hiện trong tham chiếu thẻ bộ công cụ JSDOC nhưng không được coi là một phần của Google Style hợp lệ.
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
04 hoặc /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
05 - không được khuyến nghị.Không được khuyến khích.
Cú pháp:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
06/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
30Tài liệu là tác giả của một tệp hoặc chủ sở hữu của một bài kiểm tra, thường chỉ được sử dụng trong nhận xét
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
70. Thẻ /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
05 được sử dụng bởi bảng điều khiển kiểm tra đơn vị để xác định ai sở hữu kết quả kiểm tra./** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
09Cú pháp:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
10/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
31Cho biết những gì các lỗi Các thử nghiệm hồi quy chức năng thử nghiệm đã cho.
Mỗi lỗi nên có dòng
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
09 của riêng mình, để làm cho việc tìm kiếm các bài kiểm tra hồi quy dễ dàng nhất có thể./** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
12 - Khấu hao. Không được dùng.Phản đối. Không được dùng. Sử dụng dấu backticks Markdown thay thế.
Cú pháp:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
13Trong lịch sử,
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
14 được viết là /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
15./* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
32Chỉ ra rằng một thuật ngữ trong mô tả JSDOC là mã để nó có thể được định dạng chính xác trong tài liệu được tạo.
const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
50Cú pháp:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
17/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
33/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
18Cú pháp:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
19Thẻ này được sử dụng để tạo các liên kết tham chiếu chéo trong tài liệu được tạo.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
34Lưu ý lịch sử: Các thẻ @link cũng đã được sử dụng để tạo các liên kết bên ngoài trong tài liệu được tạo. Đối với các liên kết bên ngoài, thay vào đó, hãy luôn sử dụng cú pháp liên kết của Markdown: thay vào đó: @link tags have also been used to create external links in generated documentation. For external links, always use Markdown's link syntax instead:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
35/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
20Cú pháp:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
21/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
36Tham chiếu Tra cứu chức năng hoặc phương thức lớp khác.
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
22Cú pháp:
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
23/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
37Được sử dụng trong tệp FileOverView để cho biết trình duyệt nào được hỗ trợ bởi tệp.
9.1.3 Khung chú thích cụ thể
Các chú thích sau đây là cụ thể cho một khung cụ thể.
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
24 cho góc 1/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
25 cho polymer//github.com/google/closure-compiler/wiki/Polymer-Pass
9.1.4 Ghi chú về chú thích trình biên dịch đóng tiêu chuẩn
Các thẻ sau đây được sử dụng là tiêu chuẩn nhưng hiện không được chấp nhận.
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
26 - Khấu hao. Không được dùng.Phản đối. Không được dùng. Thay vào đó, sử dụng
49 và/hoặc const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
87.goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
29 - Khấu hao. Không được dùng.Phản đối. Không được dùng. Sử dụng
59 thay thế.const /** !Array */ exportedArray = [1, 2, 3];
const /** !Array */ moduleLocalArray = [4, 5, 6];
/** @return {number} */
function moduleLocalFunction[] {
return moduleLocalArray.length;
}
/** @return {number} */
function exportedFunction[] {
return moduleLocalFunction[] * 2;
}
exports = {exportedArray, exportedFunction};
9.2 Quy tắc phong cách thường bị hiểu lầm
Dưới đây là một tập hợp các sự thật ít được biết đến hoặc thường bị hiểu lầm về phong cách Google cho JavaScript. [Sau đây là những câu nói thực; đây không phải là danh sách các huyền thoại.]
- Cả tuyên bố bản quyền và tín dụng
04 đều không được yêu cầu trong một tệp nguồn. [Cả hai cũng không được đề xuất rõ ràng.]/** @const {number} */ exports.CONSTANT_ONE = 1; /** @const {string} */ exports.CONSTANT_TWO = 'Another constant';
- Không có quy tắc cứng và nhanh điều chỉnh cách đặt hàng các thành viên của một lớp [??].
- Các khối trống thường có thể được biểu diễn chính xác là
81, như chi tiết trong [??].goog.module['search.urlHistory.UrlHistoryService'];
- Chỉ thị chính của việc bao bọc dòng là: thích phá vỡ ở cấp độ cú pháp cao hơn [??].
- Các ký tự không phải ASCII được cho phép trong các chuỗi chữ, nhận xét và JSDOC, và trên thực tế được khuyến nghị khi chúng làm cho mã dễ đọc hơn so với Escape unicode tương đương sẽ [??].
Các công cụ sau đây tồn tại để hỗ trợ các khía cạnh khác nhau của Google Style.
9.3.1 Trình biên dịch đóng
Chương trình này thực hiện kiểm tra loại và các kiểm tra, tối ưu hóa khác và các phép biến đổi khác [chẳng hạn như hạ thấp mã ECMAScript 6 đến ECMAScript 5].
9.3.2 goog.module['search.urlHistory.UrlHistoryService'];
71
goog.module['search.urlHistory.UrlHistoryService'];
Chương trình này định dạng lại mã nguồn JavaScript thành Google Style và cũng tuân theo một số thực tiễn định dạng không có khả năng yêu cầu nhưng thường xuyên có khả năng đọc. Đầu ra được sản xuất bởi
goog.module['search.urlHistory.UrlHistoryService'];
71 tuân thủ hướng dẫn kiểu.goog.module['search.urlHistory.UrlHistoryService'];
71 là không cần thiết. Các tác giả được phép thay đổi đầu ra của nó và người đánh giá được phép yêu cầu những thay đổi đó; Tranh chấp được thực hiện theo cách thông thường. Tuy nhiên, Subtrees có thể chọn chọn tham gia vào việc thực thi như vậy tại địa phương.9.3.3 Linter trình biên dịch đóng cửa
Chương trình này kiểm tra một loạt các sai lầm và chống lại.
9.3.4 Khung phù hợp
Khung tuân thủ JS là một công cụ là một phần của trình biên dịch đóng cung cấp cho các nhà phát triển một phương tiện đơn giản để chỉ định một bộ kiểm tra bổ sung để chạy so với cơ sở mã của họ trên các kiểm tra tiêu chuẩn. Ví dụ, kiểm tra sự phù hợp có thể cấm truy cập vào một thuộc tính nhất định hoặc gọi đến một chức năng nhất định hoặc thiếu thông tin loại [chưa biết].
Các quy tắc này thường được sử dụng để thực thi các hạn chế quan trọng [như xác định toàn cầu, có thể phá vỡ cơ sở mã] và các mẫu bảo mật [như sử dụng
goog.module['my.test.helpers'];
goog.module.declareLegacyNamespace[];
goog.setTestOnly[];
84 hoặc gán cho /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
37] hoặc lỏng lẻo hơn để cải thiện chất lượng mã.Để biết thêm thông tin, hãy xem Tài liệu chính thức cho Khung tuân thủ JS.
9.4 Ngoại lệ cho các nền tảng kế thừa
9.4.1 Tổng quan
Phần này mô tả các ngoại lệ và các quy tắc bổ sung sẽ được tuân thủ khi cú pháp ECMAScript 6 hiện đại không có sẵn cho các tác giả mã. Các trường hợp ngoại lệ cho kiểu được đề xuất là không cần thiết khi ECMAScript 6 cú pháp là không thể và được phác thảo ở đây:
- Việc sử dụng các khai báo
37 được cho phépgoog.module['foo.bar']; // 'foo.bar.qux' would be fine, though goog.module['foo.bar.baz'];
- Sử dụng
31 được cho phépgoog.module['my.test.helpers']; goog.module.declareLegacyNamespace[]; goog.setTestOnly[];
- Các tham số tùy chọn mà không có giá trị mặc định được cho phép
9.4.2 Sử dụng goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37
9.4.2.1 goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 Khai báo không bị bao gồmCác khai báo
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 được bắt đầu đến đầu hàm, tập lệnh hoặc mô -đun kèm theo gần nhất, có thể gây ra hành vi bất ngờ, đặc biệt là với các đóng chức chức năng tham chiếu các khai báo ____337 bên trong các vòng lặp. Mã sau đây đưa ra một ví dụ:/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
389.4.2.2 Khai báo các biến càng gần càng tốt để sử dụng đầu tiênMặc dù các khai báo
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 được bắt đầu đến khi bắt đầu hàm kèm theo, các khai báo goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 nên càng gần càng tốt với mục đích sử dụng đầu tiên của chúng, cho mục đích đọc. Tuy nhiên, không đặt khai báo goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 bên trong một khối nếu biến đó được tham chiếu bên ngoài khối. Ví dụ:/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
399.4.2.3 Sử dụng @const cho các biến hằng sốĐối với các khai báo toàn cầu trong đó từ khóa
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
33 sẽ được sử dụng, nếu có sẵn, hãy chú thích khai báo goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 với @const thay thế [đây là tùy chọn cho các biến cục bộ].9.4.3 Không sử dụng khai báo các chức năng phạm vi khối
Không làm điều này:not do this:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
40Trong khi hầu hết các máy ảo JavaScript được triển khai trước các khai báo chức năng hỗ trợ ECMAScript 6 trong các khối, nó không được tiêu chuẩn hóa. Việc triển khai không phù hợp với nhau và với hành vi ECMAScript 6 tiêu chuẩn hiện nay đối với khai báo chức năng phạm vi khối. ECMAScript 5 và trước chỉ cho phép khai báo chức năng trong danh sách câu lệnh gốc của tập lệnh hoặc hàm và cấm chúng một cách rõ ràng trong phạm vi khối ở chế độ nghiêm ngặt.
Để có được hành vi nhất quán, thay vào đó, hãy sử dụng
goog.module['foo.bar']; // 'foo.bar.qux' would be fine, though
goog.module['foo.bar.baz'];
37 được khởi tạo với biểu thức chức năng để xác định hàm trong một khối:/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
419.4.4 Quản lý phụ thuộc với ________ 218/________ 174
9.4.4.1 Tóm tắtCẢNH BÁO:
18 Quản lý phụ thuộc không được chấp nhận. Tất cả các tệp mới, ngay cả trong các dự án sử dụng goog.module['search.urlHistory.UrlHistoryService'];
18 cho các tệp cũ hơn, nên sử dụng goog.module['search.urlHistory.UrlHistoryService'];
66. Các quy tắc sau đây chỉ dành cho các tệp /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
18 trước đó. All new files, even in projects using goog.module['search.urlHistory.UrlHistoryService'];
goog.module['search.urlHistory.UrlHistoryService'];
18 for older files, should use /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66. The following rules are for pre-existing goog.module['search.urlHistory.UrlHistoryService'];
18 files only.- Đặt tất cả các
18 đầu tiên,goog.module['search.urlHistory.UrlHistoryService'];
74s thứ hai. Cung cấp riêng biệt từ yêu cầu với một dòng trống./* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
- Sắp xếp các mục theo thứ tự bảng chữ cái [chữ hoa đầu tiên].
- Đừng bao bọc các câu lệnh
18 vàgoog.module['search.urlHistory.UrlHistoryService'];
74. Vượt quá 80 cột nếu cần thiết./* Poor: the reader has no idea what character this is. */ const units = '\u03bcs';
- Chỉ cung cấp các biểu tượng cấp cao nhất.
Các câu
goog.module['search.urlHistory.UrlHistoryService'];
18 nên được nhóm lại với nhau và đặt đầu tiên. Tất cả các tuyên bố /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 nên tuân theo. Hai danh sách nên được phân tách bằng một dòng trống.Tương tự như các câu lệnh nhập trong các ngôn ngữ khác, các câu lệnh
goog.module['search.urlHistory.UrlHistoryService'];
18 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 nên được viết trong một dòng, ngay cả khi chúng vượt quá giới hạn độ dài dòng 80 cột.Các dòng phải được sắp xếp theo thứ tự bảng chữ cái, với các chữ cái viết hoa đầu tiên:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
42Tất cả các thành viên được xác định trên một lớp phải nằm trong cùng một tệp. Chỉ các lớp cấp cao nhất nên được cung cấp trong một tệp chứa nhiều thành viên được xác định trên cùng một lớp [ví dụ: các lớp enum, lớp bên trong, v.v.].
Làm cái này:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
43Không phải cái này:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
44Các thành viên trên các không gian tên cũng có thể được cung cấp:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
459.4.4.2 Bí danh với /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64CẢNH BÁO:
64 bị phản đối. Các tệp mới không nên sử dụng /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 ngay cả trong các dự án có cách sử dụng /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 hiện có. New files should not use /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 even in projects with existing /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 usage./** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 có thể được sử dụng để rút ngắn các tham chiếu đến các ký hiệu theo tên trong mã bằng cách sử dụng ________ 218/________ 174 Quản lý phụ thuộc.Chỉ có thể thêm một lời mời
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 cho mỗi tệp. Luôn luôn đặt nó trong phạm vi toàn cầu.Lời cầu khẩn
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
72 mở đầu phải được đi trước bằng chính xác một dòng trống và tuân theo bất kỳ câu lệnh goog.module['search.urlHistory.UrlHistoryService'];
18, các câu lệnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 hoặc nhận xét cấp cao nhất. Việc gọi phải được đóng trên dòng cuối cùng trong tệp. Nối /** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
75 vào câu lệnh đóng của phạm vi. Tách xét nhận xét từ dấu chấm phẩy bằng hai không gian.Tương tự như các không gian tên C ++, không thụt vào trong các khai báo
/** @const {number} */
exports.CONSTANT_ONE = 1;
/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64. Thay vào đó, hãy tiếp tục từ cột 0.Chỉ tạo bí danh cho các tên sẽ không được gán lại cho một đối tượng khác [ví dụ: hầu hết các hàm tạo, enum và không gian tên]. Không làm điều này [xem bên dưới để biết cách làm bí danh một hàm tạo]:
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
46Tên phải giống như tài sản cuối cùng của toàn cầu mà chúng là bí danh.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
479.4.4.3 goog.module['search.urlHistory.UrlHistoryService'];
25Thích sử dụng
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 thay vì goog.module['search.urlHistory.UrlHistoryService'];
25 để phá vỡ các phụ thuộc tròn giữa các tệp trong cùng một thư viện.Không giống như /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74, câu lệnh /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 được phép nhập không gian tên trước khi được xác định.goog.module['search.urlHistory.UrlHistoryService'];
25 vẫn có thể được sử dụng trong mã di sản để phá vỡ các tài liệu tham khảo tròn kéo dài qua các ranh giới thư viện, nhưng mã mới hơn nên được cấu trúc để tránh nó.Các tuyên bố
goog.module['search.urlHistory.UrlHistoryService'];
25 phải tuân theo các quy tắc kiểu tương tự như /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75.Toàn bộ khối goog.module['search.urlHistory.UrlHistoryService'];
25, /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và /* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 được sắp xếp theo thứ tự bảng chữ cái.