Chức năng javascript cho người mới bắt đầu

Tài liệu này đóng vai trò là định nghĩa đầy đủ về các tiêu chuẩn viết mã của Google dành cho mã nguồn bằng ngôn ngữ lập trình JavaScript. Tệp nguồn JavaScript được mô tả là ở trong Google Style khi và chỉ khi nó tuân thủ các quy tắc ở đây

Show

Giống như các hướng dẫn về phong cách lập trình khác, các vấn đề được đề cập không chỉ bao gồm các vấn đề thẩm mỹ về định dạng mà còn cả các loại quy ước hoặc tiêu chuẩn viết mã khác. Tuy nhiên, tài liệu này tập trung chủ yếu vào các quy tắc cứng rắn và nhanh chóng mà chúng tôi tuân theo trên toàn cầu và tránh đưa ra lời khuyên không thể thực thi rõ ràng (dù là do con người hay công cụ)

1. 1 Ghi chú thuật ngữ

Trong tài liệu này, trừ khi được giải thích khác

  1. Thuật ngữ nhận xét luôn đề cập đến nhận xét triển khai. Chúng tôi không sử dụng cụm từ nhận xét tài liệu, thay vào đó sử dụng thuật ngữ chung “JSDoc” cho cả văn bản mà con người có thể đọc được và chú thích mà máy có thể đọc được trong phạm vi

    /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    48

  2. Hướng dẫn Phong cách này sử dụng thuật ngữ RFC 2119 khi sử dụng các cụm từ phải, không được, 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 câu mệnh lệnh và tuyên bố 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 toàn bộ tài liệu

1. 2 Ghi chú hướng dẫn

Mã ví dụ trong tài liệu này là phi quy chuẩn. Nghĩa là, trong khi các ví dụ ở trong Google Style, chúng có thể không minh họa cách duy nhất để thể hiện 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

2 Thông tin cơ bản về tệp nguồn

2. 1 Tên tệp

Tên tệp phải là chữ thường và có thể bao gồm 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 chấm câu bổ sung. Thực hiện theo quy ước mà dự án của bạn sử dụng. Phần mở rộng của tên tệp phải là
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
51

2. 2 Mã hóa tập tin. UTF-8

Các tệp nguồn được mã hóa bằng 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ự khoảng cách ngang ASCII (0x20) là ký tự khoảng trắng duy nhất xuất hiện ở bất kỳ đâu trong tệp nguồn. Điều này ngụ ý rằng

  1. Tất cả các ký tự khoảng trắng khác trong chuỗi ký tự được thoát và

  2. Các ký tự tab không được sử dụng để thụt lề

2. 3. 2 Trình tự thoát hiểm đặc biệt

Đối với bất kỳ ký tự nào có trình tự thoát đặc biệt (_______0_______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), trình tự đó được sử dụng thay vì trình tự thoát số tương ứng (e. g
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
61,
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
62, hoặc
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
63). Thoát bát phân kế thừa không bao giờ được sử dụng

2. 3. 3 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ế (e. g.

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
64) hoặc bộ thoát hex hoặc Unicode tương đương (e. g.
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
65) được sử dụng, chỉ phụ thuộc vào cái nào làm cho mã dễ đọc và dễ hiểu hơn

Mẹo. Trong trường hợp thoát Unicode và đôi khi ngay cả khi các ký tự Unicode thực đượ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. Đừng bao giờ làm cho mã của bạn khó đọc hơn chỉ vì sợ rằng một số chương trình có thể không xử lý đúng các ký tự không phải ASCII. Nếu điều đó xảy ra, các chương trình đó bị hỏng và chúng phải được sửa

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 (tệp chứa lệnh 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âu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
68 và ________0____69). Các tập tin bao gồm những điều sau đây, theo thứ tự

  1. Thông tin giấy phép hoặc bản quyền, nếu có
  2. /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    70 JSDoc, nếu có
  3. Câu lệnh
    /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    66, nếu tệp
    /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    66
  4. ES
    /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    68 câu lệnh, nếu một mô-đun ES
  5. 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
  6. Việc triển khai tệp

Chính xác một dòng trống phân tách từng phần hiện có, ngoại trừ việc triển khai tệp, có thể có 1 hoặc 2 dòng trống trước

3. 1 Giấy phép hoặc thông tin bản quyền, nếu có

Nếu thông tin giấy phép hoặc bản quyền thuộc về một tệp, thì 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ó

Xem 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ố

All

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 files must declare exactly one
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 name on a single line. 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 ngắt dòng 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 google. mô-đun là những gì xác định một không gian tên. Đó là tên gói (một mã định danh phản ánh đoạn cấu trúc thư mục chứa mã) cộng với, tùy chọn, lớp/enum/giao diện chính mà nó xác định được nối vào cuối

Ví dụ

goog.module('search.urlHistory.UrlHistoryService');

3. 3. 1 thứ bậc

Không gian tên mô-đun 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

không được phép

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, sao cho các thư mục con được lồng sâu hơn là thư mục con của thư mục mẹ 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ẹ" nhất thiết phải biết tất cả các không gian tên con, 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

Câu lệnh duy nhất

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 có thể tùy chọn được theo sau bởi lệnh gọi tới
/* 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ể

Ví dụ

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 sau không gian tên cha, nên tên này không được là con hoặc cha 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 như
/* 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)

3. 3. 3 /* Poor: the reader has no idea what character this is. */ const units = '\u03bcs'; 66 Xuất khẩu

Các lớp, enum, hàm, hằng số và các ký hiệu khác được xuất bằng cách sử dụng đối tượng

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
92. Các biểu tượng đã 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 được khai báo cục bộ và được xuất riêng. 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-cục bộ không được xuất khẩu không đượ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 không kết thúc bằng dấu gạch dưới. Không có thứ tự theo quy định cho các ký hiệu được xuất và mô-đun-cục bộ

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};
/** @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 trình biên dịch coi là hằng số

/** @const */
exports = {exportedFunction};

3. 4 mô-đun ES

3. 4. 1 Nhập khẩu

Báo cáo nhập khẩu không được ngắt dòng 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ập

Cá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. Đừng
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 mô-đun ES khác

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
3. 4. 1. 1. 1 Phần mở rộng tệp trong đường dẫn nhập

Phần 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 đường dẫn nhập và phải luôn được đưa vào

import '../directory/file';
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
0

Không nhập cùng một tệp nhiều lần. Điều này có thể gây khó khăn cho việc xác định số lần nhập tổng hợp của một tệp

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
1
3. 4. 1. 3 Đặt tên nhập khẩu
3. 4. 1. 3. 1 Nhập mô-đun đặt tên

Tên nhập mô-đun (

goog.module('search.urlHistory.UrlHistoryService');
00) là tên
goog.module('search.urlHistory.UrlHistoryService');
01 được lấy từ tên tệp đã nhập

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
2
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
33. 4. 1. 3. 2 Đặt tên nhập khẩu mặc định

Tê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';
4

Ghi chú. Nói chung, điều này sẽ không xảy ra vì hướng dẫn kiểu này cấm xuất mặc định, xem. Nhập mặc định chỉ được sử dụng để nhập các mô-đun không tuân theo hướng dẫn kiểu này

3. 4. 1. 3. 3 Đặt tên cho hàng nhập đã đặt tên

Nói chung, các ký hiệu được nhập thông qua quá trình nhập có tên (

goog.module('search.urlHistory.UrlHistoryService');
02) nên giữ nguyên tên. Tránh nhập bí danh (
goog.module('search.urlHistory.UrlHistoryService');
03). Thích sửa xung đột tên bằng cách sử dụng mô-đun nhập (_______35_______04) hoặc tự đổi tên bản xuất

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
5

Nếu cần đổi tên một mục nhập đã đặ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';
6

3. 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-cục bộ không được xuất khẩu không đượ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 không kết thúc bằng dấu gạch dưới. Không có thứ tự theo quy định cho các ký hiệu được xuất và mô-đun-cục bộ

3. 4. 2. 1 Xuất khẩu được đặt tên và mặc định

Sử dụng xuất khẩu có 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 cho 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 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 giữa 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';
9
3. 4. 2. 2 Xuất các lớp và đối tượng vùng chứa tĩnh

Không xuất các lớp hoặc đối tượng vùng chứa bằng các phương thức hoặc thuộc tính tĩnh vì mục đích tạo không gian tên

goog.module('search.urlHistory.UrlHistoryService');
0

Thay vào đó, hãy xuất các hằng số và hàm riêng lẻ

goog.module('search.urlHistory.UrlHistoryService');
1
3. 4. 2. 3 Tính biến động của hàng xuất khẩu

Các biến đã xuất không được thay đổi bên ngoài quá trình khởi tạo mô-đun

Có các lựa chọn thay thế nếu cần thay đổi, bao gồm xuất một tham chiếu không đổi đến một đối tượng có các trường có thể thay đổi hoặc xuất các hàm truy cập cho dữ liệu có thể thay đổi

goog.module('search.urlHistory.UrlHistoryService');
2
goog.module('search.urlHistory.UrlHistoryService');
3
3. 4. 2. 4 xuất khẩu từ

Các câu lệnh

goog.module('search.urlHistory.UrlHistoryService');
08 không được ngắt dòng 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ả hương vị
goog.module('search.urlHistory.UrlHistoryService');
08

goog.module('search.urlHistory.UrlHistoryService');
4

3. 4. 3 vòng phụ thuộc trong các mô-đun ES

Không tạo chu kỳ giữa các mô-đun ES, mặc dù đặc tả ECMAScript cho phép điều này. Lưu ý rằng có thể tạo chu trình bằng 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');
5
goog.module('search.urlHistory.UrlHistoryService');
6
goog.module('search.urlHistory.UrlHistoryService');
7

3. 4. 4 Tương tác với Đóng cửa

3. 4. 4. 1 Tham khảo google

Để tham chiếu không gian tên Closure

goog.module('search.urlHistory.UrlHistoryService');
12, nhập Closure's
goog.module('search.urlHistory.UrlHistoryService');
13

goog.module('search.urlHistory.UrlHistoryService');
8

goog.module('search.urlHistory.UrlHistoryService');
13 chỉ xuất một tập hợp con các thuộc tính từ
goog.module('search.urlHistory.UrlHistoryService');
12 toàn cầu có thể được sử dụng trong các mô-đun ES

3. 4. 4. 2 tốt. yêu cầu trong các mô-đun ES

Các mô-đun

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 trong ES hoạt động giố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 Closure nào (i. e. , 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');
9
3. 4. 4. 3 Khai báo ID mô-đun đóng trong mô-đun ES

Có thể sử dụng

goog.module('search.urlHistory.UrlHistoryService');
21 trong các mô-đun ES để khai báo ID mô-đun giống như
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66. Đ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,
goog.module('search.urlHistory.UrlHistoryService');
25'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 cho
/* 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

Một

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 (hoặc
goog.module('search.urlHistory.UrlHistoryService');
24) cho ID mô-đun từ
goog.module('search.urlHistory.UrlHistoryService');
21 sẽ luôn trả về đối tượng mô-đun (như thể nó là
goog.module('search.urlHistory.UrlHistoryService');
04'd). Kết quả là, đối số của
goog.module('search.urlHistory.UrlHistoryService');
21 phải luôn kết thúc bằng ____35_______33

Ghi chú. Có lỗi khi gọi

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
81 trong mô-đun ES, nó chỉ có thể được gọi từ tệp
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66. Không có cách nào trực tiếp để liên kết một không gian tên kế thừa với một mô-đun ES

Chỉ nên sử dụng

goog.module('search.urlHistory.UrlHistoryService');
21 để nâng cấp tệp Đóng lên mô-đun ES tại chỗ, nơi sử dụng xuất khẩu có tên

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
0

3. 5 goog.module('search.urlHistory.UrlHistoryService'); 37

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 chọn được theo sau bởi lệnh gọi tới
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 chọn được theo sau bởi một lệnh gọi tới
goog.module('search.urlHistory.UrlHistoryService');
40

3. 6 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

Nhập khẩu được thực hiện với 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 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à chú thích loại, trong khi những tên được nhập bởi một
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
75 chỉ có thể được sử dụng trong 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ó dòng trống. Khối này theo tuyên bố
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 được tách ra. Toàn bộ đối số của
/* 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à một không gian tên được xác định bởi một
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
66 trong một tệp riêng biệt. 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 không được 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 cố định duy nhất hoặc nếu không sẽ bị hủy cấu trúc thành một số bí danh cố định. Các bí danh này là cách duy nhất được chấp nhận để chỉ các phụ thuộc trong chú thích loại hoặc mã. Không được sử dụng các không gian tên đầy đủ ở bất kỳ đâu, ngoại trừ làm đố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

Ngoại lệ. Các loại, biến và hàm được khai báo trong tệp bên ngoài phải sử dụng tên đủ điều kiện của chúng trong chú thích loại và mã

Bí danh phải khớp với thành phần cuối cùng được phân tách bằng dấu chấm trong 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 bí danh dài hơn. Bí danh kết quả phải giữ lại cách viết hoa của mã định danh ban đầu để nó vẫn xác định chính xác loại của nó. Các bí danh dài hơn có thể được sử dụng để phân biệt 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 một bí danh dài hơn để ngăn che giấu các loại gốc như

goog.module('search.urlHistory.UrlHistoryService');
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 API Web và Đối tượng tích hợp sẵn tiêu chuẩn tại MDN). Khi đổi tên các bí danh bị hủy cấu trúc, một khoảng trắng phải theo sau dấu hai chấm theo yêu cầu trong

Một tệp không được chứa cả câu lệnh

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 và câu lệnh
/* 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 chú thích mã và loại, thì tên đó phải đượ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 được nhập chỉ vì tác dụng phụ của nó, lệnh gọi phải là __________74 (không phải __________75) và phép gán có thể bị bỏ qua. Cần có một bình luận để giải thích lý do tại sao điều này là cần thiết và loại bỏ cảnh báo của 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ả các yêu cầu có tên ở phía bên trái được ưu tiên trước, được sắp xếp theo thứ tự bảng chữ cái của các tên đó. Sau đó, yêu cầu phá hủy, được sắp xếp lại theo tên ở phía bên trái. Cuối cùng, bất kỳ cuộc gọi yêu cầu nào độc lập (thường là những cuộc gọi này 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 các yêu cầu không được sắp xếp chính xác

Nếu một bí danh hoặc tên mô-đun dài sẽ khiến một dòng vượt quá giới hạn 80 cột, thì nó không được ngắt dòng. các dòng yêu cầu là một ngoại lệ đối với giới hạn 80 cột

Ví dụ

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
1

nản lòng

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
2

không được phép

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
3

3. 7 Việc triển khai tệp

Việc triển khai thực tế diễn ra sau khi tất cả thông tin phụ thuộc được khai báo (cách nhau í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-cục bộ nào (hằng, biến, lớp, hàm, v.v.), cũng như bất kỳ biểu tượng được xuất nào

4 Định dạng

Lưu ý thuật ngữ. cấu trúc giống như khối đề cập đến phần thân của một lớp, hàm, phương thức hoặc khối mã được phân cách bằng dấu ngoặc nhọn. Lưu ý rằng, by và , bất kỳ mảng hoặc đối tượng theo nghĩa đen nào cũng có thể tùy ý được xử lý như thể nó là một cấu trúc giống như khối

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 hoạt động đúng trên các tệp JavaScript.
goog.module('search.urlHistory.UrlHistoryService');
71 có tích hợp với một số trình soạn thảo 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 (i. e.

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ỳ câu lệnh nào khác), ngay cả khi phần nội dung chỉ chứa một câu lệnh duy nhất. Câu lệnh đầu tiên của một khối không trống phải bắt đầu trên dòng của chính nó

không được phép

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
4

Ngoại lệ. Một câu lệnh if đơn giản có thể vừa khít hoàn toàn trên một dòng mà không có dòng xuống dòng (và không có dòng nào khác) có thể được giữ trên một dòng không có dấu ngoặc 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ỏ dấu ngoặc nhọn và dòng mới

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
5

4. 1. 2 khối rỗng. phong cách K&R

Dấu ngoặc theo kiểu Kernighan và Ritchie (dấu ngoặc của người 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 ngắt dòng trước dấu ngoặc mở
  • Ngắt dòng sau cú đúp mở đầu
  • Ngắt dòng trước dấu ngoặc nhọn
  • Ngắt dòng sau dấu ngoặc nhọn nếu dấu ngoặc nhọn đó kết thúc 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 thức lớp. Cụ thể, không có ngắt dòng sau dấu ngoặc nhọn nếu nó được theo sau bởi ________ 35_______74, ________ 35_______79, ________ 35_______77 hoặc dấu phẩy, dấu chấm phẩy hoặc dấu ngoặc đơn bên phải

Ví dụ

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
6

4. 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 lại ngay sau khi nó được mở ra, không có ký tự, dấu cách hoặc ngắt dòng ở giữa (i. e.

goog.module('search.urlHistory.UrlHistoryService');
81), trừ khi nó là một phần của câu lệnh nhiều khối (câu lệnh chứa trực tiếp nhiều khối.
goog.module('search.urlHistory.UrlHistoryService');
73/______35_______74 hoặc
goog.module('search.urlHistory.UrlHistoryService');
84/
goog.module('search.urlHistory.UrlHistoryService');
79/
goog.module('search.urlHistory.UrlHistoryService');
86)

Ví dụ

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
7

không được phép

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
8

4. 2 Khối thụt đầu dòng. +2 dấu cách

Mỗi khi một khối mới hoặc cấu trúc giống như khối được mở, phần thụt lề sẽ tăng thêm hai khoảng trắng. Khi khối kết thúc, thụt lề trở về mức thụt lề trước đó. Mức thụt lề áp dụng cho cả mã và nhận xét trong toàn bộ khối. (Xem ví dụ trong)

4. 2. 1 mảng chữ. giống như khối tùy chọn

Bất kỳ mảng chữ nào cũng có thể được định dạng tùy chọn như thể nó là một “cấu trúc giống như khối. ” Ví dụ: tất cả những điều sau đây đều hợp lệ (không phải là danh sách đầy đủ)

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
9
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
0

Cá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 phần tử, nhưng không nên chỉ được sử dụng để giảm kích thước dọc của các mảng lớn hơn

4. 2. 2 đối tượng chữ. giống như khối tùy chọn

Bất kỳ đối tượng theo nghĩa đen nào cũng có thể được định dạng tùy chọn 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ụ: tất cả những điều sau đây đều hợp lệ (không phải là danh sách đầy đủ)

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
1
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
2

4. 2. 3 Lớp chữ

Các ký tự lớp (dù là khai báo hay biểu thức) được thụt vào dưới dạng khối. Không thêm dấu chấm phẩy sau các phương thức hoặc sau dấu ngoặc nhọn đóng của một khai báo lớp (các câu lệnh—chẳng hạn như các phép gán—có chứa các biểu thức lớp vẫn được kết thúc bằng dấu chấm phẩy). Sử dụng từ khóa

goog.module('search.urlHistory.UrlHistoryService');
87, nhưng không sử dụng chú thích
goog.module('search.urlHistory.UrlHistoryService');
88 JSDoc trừ khi lớp mở rộng một loại được tạo khuôn mẫu

Ví dụ

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
3
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
4

4. 2. 4 Biểu thức hàm

Khi khai báo một hàm ẩn danh trong danh sách các đối số cho một lệnh gọi hàm, phần thân của hàm được thụt lề nhiều hơn hai khoảng trắng so với độ sâu thụt lề trước đó

Ví dụ

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
5

4. 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 khối chuyển đổi được thụt vào +2

Sau nhãn chuyển đổi, một dòng mới xuất hiện và mức thụt đầu dòng được tăng lên +2, chính xác như thể một khối đang đượ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 công tắc sau trở về mức thụt đầu dòng trước đó, như thể một khối đã bị đóng

Một dòng trống là tùy chọn giữa một

goog.module('search.urlHistory.UrlHistoryService');
89 và trường hợp sau

Ví dụ

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
6

4. 3 Tuyên bố

4. 3. 1 Một câu lệnh trên mỗi dòng

Mỗi câu lệnh được theo sau bởi một dấu ngắt dòng

4. 3. 2 dấu chấm phẩy là bắt buộc

Mọi câu lệnh phải được kết thúc bằng dấu chấm phẩy. Dựa vào chèn dấu chấm phẩy tự động bị cấm

4. 4 Giới hạn cột. 80

Mã JavaScript có giới hạn cột là 80 ký tự. Ngoại trừ như được lưu ý bên dưới, bất kỳ dòng nào vượt quá giới hạn này đều phải được ngắt dòng, như được giải thích trong

ngoại lệ

  1. Câu lệnh
    /* 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';
    
    74 và
    /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    75 (xem và )
  2. Câu lệnh mô-đun ES
    /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    68 và
    goog.module('search.urlHistory.UrlHistoryService');
    
    08 (xem và )
  3. Các dòng không thể tuân theo giới hạn cột hoặc sẽ cản trở khả năng khám phá. Những ví dụ bao gồm
    • Một URL dài có thể nhấp được trong nguồn
    • Một lệnh trình bao dự định được sao chép và dán
    • Một chuỗi ký tự dài có thể cần được sao chép hoặc tìm kiếm toàn bộ (e. g. , một đường dẫn tệp dài)

4. 5 Đóng gói dòng

Lưu ý thuật ngữ. Ngắt dòng đang chia một đoạn mã thành nhiều dòng để tuân theo giới hạn của cột, trong đó đoạn mã đó có thể nằm gọn trong một dòng một cách hợp pháp

Không có công thức toàn diện, xác định nào chỉ ra chính xác cách ngắt dòng trong mọi tình huống. Rất thường có một số cách hợp lệ để ngắt dòng cùng một đoạn mã

Ghi chú. Mặc dù lý do điển hình của việc ngắt dòng là để tránh vượt quá giới hạn cột, nhưng ngay cả mã thực tế phù hợp với giới hạn cột cũng có thể được ngắt dòng theo quyết định của tác giả

Mẹo. Trích xuất một phương thức hoặc biến cục bộ có thể giải quyết vấn đề mà không cần phải ngắt dòng

4. 5. 1 Nơi để phá vỡ

Chỉ thị chính của line-wrapping là. thích phá vỡ ở cấp độ cú pháp cao hơn

ưa thích

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
7

nản lòng

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
8

Trong ví dụ trước, các mức cú pháp từ cao nhất đến thấp nhất như sau. gán, chia, gọi hàm, tham số, hằng số

Toán tử được gói như sau

  1. Khi một dòng bị ngắt tại một toán tử, dấu ngắt xuất hiện sau ký hiệu. (Lưu ý rằng đây không phải là cách làm tương tự được sử dụng theo phong cách Google dành cho Java. )
    1. Điều này không áp dụng cho dấu chấm (
      goog.module('search.urlHistory.UrlHistoryService');
      
      95), thực ra không phải là toán tử
  2. Tên phương thức hoặc hàm tạo được gắn vào dấu ngoặc đơn mở (
    goog.module('search.urlHistory.UrlHistoryService');
    
    96) theo sau nó
  3. Dấu phẩy (
    goog.module('search.urlHistory.UrlHistoryService');
    
    97) được gắn vào mã thông báo đứng trước nó

Ghi chú. Mục tiêu chính của việc ngắt dòng là có mã rõ ràng, không nhất thiết là mã phù hợp với số lượng dòng nhỏ nhất

4. 5. 2 dòng tiếp tục thụt lề ít nhất +4 dấu cách

Khi ngắt dòng, mỗi dòng sau dòng đầu tiên (mỗi dòng tiếp theo) được thụt vào ít nhất +4 so với dòng ban đầu, trừ khi nó tuân theo quy tắc thụt lề khối

Khi có nhiều dòng tiếp tục, thụt đầu dòng có thể 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 vào 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 đầu dòng khi và chỉ khi chúng bắt đầu bằng các phần tử song song về mặt cú pháp

giải quyết thực tiễn không khuyến khích sử dụng một số khoảng trắng khác nhau để căn chỉnh các mã thông báo nhất định với các dòng trước đó

4. 6 Khoảng trắng

4. 6. 1 Khoảng trắng dọc

Một dòng trống duy nhất xuất hiện

  1. Giữa các phương thức liên tiếp trong một lớp hoặc đối tượng theo nghĩa đen
    1. Ngoại lệ. Một dòng trống giữa hai định nghĩa thuộc tính liên tiếp trong một đối tượng bằng chữ (không có mã nào khác giữa chúng) là tùy chọn. Các dòng trống như vậy được sử dụng khi cần thiết để tạo các nhóm trường hợp lý
  2. Trong nội dung phương thức, tiết kiệm để tạo các nhóm câu lệnh logic. Các dòng trống ở đầu hoặc cuối thân hàm không được phép
  3. Tùy chọn trước phương thức đầu tiên hoặc sau phương thức 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 được khuyến khích)
  4. Theo yêu cầu của các phần khác của tài liệu này (e. g. )

Nhiều dòng trống liên tiếp được cho phép, nhưng không bao giờ bắt buộc (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à thuộc ba loại chính. đầu (ở đầu dòng), theo sau (ở cuối dòng) và nội bộ. Khoảng trắng hàng đầu (i. e. , thụt đầu dòng) được giải quyết ở nơi khác. Khoảng trắng ở cuối bị cấm

Ngoài những nơi được yêu cầu bởi ngôn ngữ hoặc các quy tắc kiểu dáng khác và ngoài chữ, nhận xét và JSDoc, một không gian ASCII bên trong cũng chỉ xuất hiện ở những vị trí sau

  1. Tách bất kỳ từ dành riêng nào (chẳng hạn như
    goog.module('search.urlHistory.UrlHistoryService');
    
    73,
    goog.module('search.urlHistory.UrlHistoryService');
    
    75 hoặc
    goog.module('search.urlHistory.UrlHistoryService');
    
    79) ngoại trừ
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    01 và
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    02, khỏi dấu ngoặc đơn mở (_______35_______96) theo sau nó trên dòng đó
  2. Tách bất kỳ từ dành riêng nào (chẳng hạn như
    goog.module('search.urlHistory.UrlHistoryService');
    
    74 hoặc
    goog.module('search.urlHistory.UrlHistoryService');
    
    79) khỏi dấu ngoặc nhọn đóng (
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    06) đứng trước từ đó trên dòng đó
  3. Trước bất kỳ dấu ngoặc nhọn mở nào (
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    07), với hai ngoại lệ
    1. Trước một ký tự đối tượng là đối số đầu tiên của một hàm hoặc phần tử đầu tiên trong một ký tự mảng (e. g.
      goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
      goog.module('foo.bar.baz');
      
      08)
    2. Trong bản mở rộng mẫu, vì nó bị cấm bởi ngôn ngữ (e. g. có hiệu lực.
      goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
      goog.module('foo.bar.baz');
      
      09, không hợp lệ.
      goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
      goog.module('foo.bar.baz');
      
      10)
  4. Trên cả hai mặt của bất kỳ toán tử nhị phân hoặc bậc ba nào
  5. Sau dấu phẩy (
    goog.module('search.urlHistory.UrlHistoryService');
    
    97) hoặc dấu chấm phẩy (
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    12). Lưu ý rằng khoảng cách không bao giờ được phép trước các ký tự này
  6. Sau dấu hai chấm (
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    13) trong một đối tượng theo nghĩa đen
  7. Ở cả hai bên của dấu gạch chéo kép (
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    14) bắt đầu nhận xét cuối dòng. Ở đây, nhiều khoảng trắng được cho phép, nhưng không bắt buộc
  8. Sau một ký tự bình luận khối mở và ở cả hai bên của các ký tự đóng (e. g. cho các khai báo kiểu dạng ngắn, ép kiểu và nhận xét tên tham số.
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    15;

4. 6. 3 Căn ngang. chán nản

Lưu ý thuật ngữ. Căn chỉnh theo chiều ngang là cách thêm một số khoảng trắng bổ sung có thể thay đổi vào mã của bạn với mục tiêu làm cho một số 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 đó

Phương pháp này được cho phép, nhưng nó thường không được Google Style khuyến khích. Thậm chí không bắt buộc phải duy trì căn chỉnh ngang ở những nơi nó đã được sử dụng

Đây là một ví dụ không có căn chỉnh, theo sau là một ví dụ có căn chỉnh. Cả hai đều được phép, nhưng cái sau không được khuyến khích

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
9

Mẹo. Căn chỉnh có thể hỗ trợ khả năng đọc, nhưng nó tạo ra các vấn đề cho việc bảo trì trong tương lai. Xem xét một thay đổi trong tương lai chỉ cần chạm vào một dòng. Thay đổi này có thể khiến định dạng hài lò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 người viết mã (có thể là bạn) đ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 định dạng lại xếp tầng. Thay đổi một dòng đó hiện có bán kính vụ nổ. Điều này tệ nhất có thể dẫn đến công việc bận rộn vô ích, nhưng tốt nhất thì 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ố hàm 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 ngắt dòng theo cách có thể đọc được. Để tiết kiệm dung lượng, bạn có thể ngắt dòng càng gần 80 càng tốt hoặc đặt mỗi đối số trên một dòng riêng để dễ đọc hơn. Thụt đầu dòng phải là bốn khoảng trắng. Căn chỉnh theo 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};
0

4. 7 Nhóm dấu ngoặc đơn. khuyến khích

Các 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ó khả năng mã sẽ bị hiểu sai nếu không có chúng, cũng như chúng sẽ không làm cho mã dễ đọc hơn. Không hợp lý khi cho rằng mọi đầu đọc đều ghi nhớ toàn bộ bảng ưu tiên toán tử

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 là bắt buộc đối với kiểu 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 xử lý riêng trong

Nhận xét khối được thụt lề ở cùng mức với mã xung quanh. Chúng có thể theo kiểu

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
28 hoặc
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
14. Đối với nhận xét nhiều dòng
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
28, các dòng tiếp theo phải bắt đầu bằng * được căn chỉnh 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ó ngữ 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};
1

Nhậ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 (_______0_______48) để nhận xét triển khai

Nhận xét "Tên tham số" 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 đầy đủ ý nghĩa và việc tái cấu trúc phương thức để rõ ràng hơn là không khả thi. Định dạng ưa thích của họ 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

Để thống nhất 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};
3

5 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 mô tả những tính năng nào có thể được sử dụng hoặc không được sử dụng và mọi ràng buộc bổ sung đối với 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

Khai báo tất cả các biến cục bộ bằng

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 gán lại. Không được sử dụng từ khóa
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
37

5. 1. 2 Mỗi khai báo một biến

Mỗi khai báo biến cục bộ chỉ khai báo một biến. khai báo chẳng hạn 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 Khai báo khi cần thiết, khởi tạo ngay khi có thể

Các biến cục bộ không được khai báo theo thói quen khi bắt đầu khối chứa hoặc cấu trúc giống như khối 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 (với lý do), để giảm thiểu phạm vi của chúng

5. 1. 4 Khai báo các loại theo yêu cầu

Các chú thích loại JSDoc có thể được thêm vào dòng phía trên khai báo hoặc nội dòng khác trước tên biến nếu không có JSDoc nào khác xuất hiện

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

Không được phép trộn các kiểu nội tuyến và JSDoc. 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};
5

Mẹo. Có nhiều trường hợp trình biên dịch có thể suy ra một kiểu đã được tạo khuôn mẫu nhưng không thể suy ra các tham số của nó. Đây là trường hợp đặc biệt khi lời gọi khởi tạo bằng chữ 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 (e. g. , mảng trống, đối tượ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');
40) hoặc nếu biến được sửa đổi trong một bao đóng. Chú thích loại biến cục bộ đặc biệt hữu ích trong những 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 chữ

5. 2. 1 Sử dụng dấu phẩy sau

Bao gồm dấu phẩy ở cuối bất cứ khi nào có dấu ngắt dòng giữa phần tử cuối cùng và dấu ngoặc đóng

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

5. 2. 2 Không sử dụng phương thức khởi tạo biến đổi
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
41

Hàm tạo 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ế

không được phé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};
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ố nguyên 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 phần 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 đưa ra và nếu đó là bất kỳ số nào khác thì đó 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};
8

Cho phép phâ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 khi thích hợp

5. 2. 3 Thuộc tính phi 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 (ngoài

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
48). Thay vào đó, hãy 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 ký tự mảng có thể được sử dụng ở phía bên trái của phép gán để thực hiện hủy (chẳng hạn như khi giải nén nhiều giá trị từ một mảng đơn hoặc có thể lặp lại). Phần tử còn lại cuối cùng có thể được bao gồm (không có khoảng cách 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};
9

Việc hủy cấu trúc 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ố là bắt buộc nhưng có thể bỏ qua). Luôn chỉ định

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
52 làm giá trị mặc định nếu tham số mảng bị hủy cấu trúc 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';
0

không được phép

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
1

Mẹo. Để (không) đóng gói nhiều giá trị vào một tham số hoặc hàm trả về, hãy ưu tiên hủy đối tượng hơn là hủy mảng khi có thể, vì nó cho phép đặt tên các phần tử riêng lẻ và chỉ định một loại khác nhau cho từng phần tử

5. 2. 5 Toán tử trải rộng

Các ký tự mảng có thể bao gồm toán tử trải rộng (

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ử trải rộng 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ó khoảng trống sau
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
51

Ví dụ

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
2

5. 3 đối tượng chữ

5. 3. 1 Sử dụng dấu phẩy sau

Bao gồm dấu phẩy ở cuối bất cứ khi nào có dấu ngắt dòng giữa thuộc tính cuối cùng và dấu ngoặc nhọn đó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

Mặc dù

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
50 không gặp vấn đề giống 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 vì tính nhất quán. Thay vào đó, hãy sử dụng một đối tượng theo nghĩa đen (
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 lẫn các phím được trích dẫn và không được trích dẫn

Các ký tự đối tượng có thể đại diện cho các cấu trúc (với các khóa và/hoặc ký hiệu không được trích dẫn) hoặc các ký tự (với các khóa được trích dẫn và/hoặc được tính toán). Không trộn lẫn các loại khóa này trong một đối tượng theo nghĩa đen

không được phép

/** @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 thuộc tính cho các hàm, 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/làm xáo trộn chuỗi ký tự

không được phép

/** @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';
5

5. 3. 4 Tên thuộc tính được tính toán

Tên thuộc tính được tính toán (e. g. ,

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à khóa kiểu chính tả (trích dẫn) (i. e. , không được trộn lẫn với các khóa không được trích dẫn) trừ khi thuộc tính được tính là ký hiệu (e. g. ,
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 được tính toán, nhưng không được trộn lẫn với các khóa không phải enum theo cùng một nghĩa đen

5. 3. 5 Phương pháp tốc ký

Các phương thức có thể được định nghĩa trên các ký tự đối tượng bằng cách sử dụng tốc ký của phương thức (

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
64) thay cho dấu hai chấm ngay sau đó là một ký tự hàm
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
01 hoặc mũi tên

Ví dụ

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
6

Lư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 thức viết tắt 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 một hàm mũi tên đề cập đến phạm vi bên ngoài đối tượng theo nghĩa đen

Ví dụ

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
7

5. 3. 6 thuộc tính tốc ký

Thuộc tính tốc ký được phép trên đối tượng chữ

Ví dụ

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
8

5. 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 nhiệm vụ để thực hiện phá hủy và giải nén nhiều giá trị từ một đối tượng

Các đối tượng bị hủy cấu trúc cũng có thể được sử dụng làm tham số chức năng, nhưng phải được giữ càng đơn giản càng tốt. một cấp duy nhất của các thuộc tính tốc ký không được trích dẫn. Các cấp độ sâu hơn của các thuộc tính được tính toán và lồng nhau có thể không được sử dụng trong quá trình 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ố đã hủy cấu trúc (

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 bản thân đối tượng đã hủy cấu trúc là tùy chọn, thì đối tượng đó phải được đặt mặc định là
goog.module('search.urlHistory.UrlHistoryService');
81. JSDoc cho tham số bị hủy cấu trúc có thể được đặt bất kỳ tên nào (tên này không được sử dụng nhưng được yêu cầu bởi trình biên dịch)

Ví dụ

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
9

không được phép

/** @const */
exports = {exportedFunction};
0

Việc hủy cấu trúc cũng có thể được sử dụng cho các câu lệnh

/* 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 bao bọc. toàn bộ câu lệnh chiếm một dòng, bất kể nó dài bao nhiêu (xem phần )

5. 3. 8 bảng liệt kê

Việ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. Enums phải là hằng số và tất cả các giá trị enum phải không thay đổi sâu sắc

/** @const */
exports = {exportedFunction};
1

5. 4 lớp

5. 4. 1 nhà xây dựng

Constructor là tùy chọn. Các hàm tạo của 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 vào
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 thức trong hàm tạo

5. 4. 2 trường

Đặt tất cả các trường của một đối tượng cụ thể (i. e. tất cả các thuộc tính khác với phương thức) trong hàm tạo. Chú thích các trường không bao giờ được chỉ định lại với

/* 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 quá bất biến). Chú thích các trường không công khai bằng chú thích khả năng hiển thị phù 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ên của tất cả các trường ________0____94 bằng 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

Ví dụ

/** @const */
exports = {exportedFunction};
2

Mẹo. Không bao giờ được thêm hoặc xóa các thuộc tính khỏi một phiên bản 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 của máy ảo. Nếu cần, 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 thay đổi hình dạng sau này. Việc 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ó thêm cái này theo mặc định

5. 4. 3 Thuộc tính tính toán

Các thuộc tính được tính chỉ có thể được sử dụng trong các lớp khi thuộc tính là một ký hiệu. Các thuộc tính kiểu chính tả (nghĩa là các khóa không phải ký hiệu được trích dẫn hoặc tính toán, 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 hợp lý. Ngoài điều này,
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ỳ biểu tượng tích hợp nào khác (e. g. ,

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 điền đầy và do đó sẽ không hoạt động trong các trình duyệt cũ hơn

5. 4. 4 phương thức tĩnh

Khi nó không ảnh hưởng đến khả năng đọc, hãy ưu tiên các hàm mô-đun cục bộ hơn các phương thức tĩnh riêng tư

Các phương thức tĩnh chỉ nên được gọi trên chính lớp cơ sở. Các phương thức tĩnh không nên được gọi 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 của lớp con (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 lớp con không xác định phương thức tĩnh.

không được phép

/** @const */
exports = {exportedFunction};
3

5. 4. 5 Khai báo lớp kiểu cũ

Mặc dù các lớp ES6 được ưu tiên hơn, nhưng có những trường hợp các lớp ES6 có thể không khả thi. Ví dụ

  1. Nếu tồn tại hoặc sẽ tồn tại các lớp con, bao gồm cả các khung tạo ra các lớp con, không thể 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, thì tất cả các lớp con xuôi dòng không sử dụng cú pháp lớp ES6 sẽ cần phải được sửa đổi

  2. Các khung yêu cầu giá trị

    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    66 đã biết trước khi gọi hàm tạo của siêu lớp, vì các hàm tạo với siêu lớp ES6 không có quyền truy cập vào giá trị của thể hiện
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    66 cho đến khi lệnh gọi tới
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    02 trả về

Trong tất cả các cách khác, hướng dẫn kiểu vẫn áp dụng cho mã này. Tất cả các tham số mặc định, phần còn lại và hàm mũi tên đều 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};
4

Ngoài ra, mặc dù

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ả mã mới, nhưng cú pháp truyền thống hơn cũng được cho phép

/** @const */
exports = {exportedFunction};
5

Các thuộc tính của mỗi cá thể phải được xác định trong hàm tạo sau lệnh gọi hàm tạo siêu lớp, nếu có một siêu lớp. Các phương thức nên được xác định trên nguyên mẫu của hàm tạo

Xác định chính xác hệ thống phân cấp nguyên mẫu của hàm tạo 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ác trực tiếp với
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
81

Từ khóa

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
97 cho phép định nghĩa lớp rõ ràng và dễ đọc hơn so với định nghĩa thuộc tính
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
81. Mã triển khai thông thường không có nghiệp vụ thao tác với các đối tượng này, mặc dù chúng vẫn hữu ích để định nghĩa các lớp như đã định nghĩa trong. Mixins và sửa đổi các nguyên mẫu của các đối tượng dựng sẵn bị cấm rõ ràng

Ngoại lệ. Mã khung (chẳng hạn như Polymer hoặc Angular) có thể cần sử dụng

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
81 và không nên sử dụng các giải pháp thậm chí còn tệ hơn để tránh làm như vậy

5. 4. 7 Getters và Setters

Do not use JavaScript getter and setter properties. Chúng có khả năng gây ngạc nhiên và khó giải thích và có sự hỗ trợ hạn chế trong trình biên dịch. Thay vào đó hãy cung cấp các phương thức thông thường

Ngoại lệ. có những tình huống không thể tránh khỏi việc xác định getter hoặc setter (e. g. các khung liên kết dữ liệu như Angular và Polymer hoặc để tương thích với các API bên ngoài không thể điều chỉnh). 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();
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

không được phép

/** @const */
exports = {exportedFunction};
6

5. 4. 8 Overriding toString

The

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
04 method may be overridden, but must always succeed and never have visible side effects

Tip. Beware, in particular, of calling other methods from toString, since exceptional conditions could lead to infinite loops

5. 4. 9 Interfaces

Interfaces may be declared with

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
05 or
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ể rõ ràng (i. e. via
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
08) or implicitly implemented by a class or object literal

All non-static method bodies on an interface must be empty blocks. Fields must be declared as uninitialized members in the class constructor

Ví dụ

/** @const */
exports = {exportedFunction};
7

5. 4. 10 Abstract Classes

Use abstract classes when appropriate. Abstract classes and methods must be annotated with

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
09. Do not use
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
10. See abstract classes and methods

5. 5 Functions

5. 5. 1 Top-level functions

Top-level functions may be defined directly on the

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
92 object, or else declared locally and optionally exported. See for more on exports

ví dụ

/** @const */
exports = {exportedFunction};
8
/** @const */
exports = {exportedFunction};
9

5. 5. 2 Nested functions and closures

Functions may contain nested function definitions. If it is useful to give the function a name, it should be assigned to a local

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
33

5. 5. 3 Arrow functions

Arrow functions provide a concise function syntax and simplify scoping

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
66 for nested functions. Prefer arrow functions over the
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
01 keyword, particularly for nested functions (but see )

Prefer arrow functions over other

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
66 scoping approaches such as
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
16,
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
17, and
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
18. Arrow functions are particularly useful for calling into callbacks as they permit explicitly specifying which parameters to pass to the callback whereas binding will blindly pass along all parameters

The left-hand side of the arrow contains zero or more parameters. Parentheses around the parameters are optional if there is only a single non-destructured parameter. When parentheses are used, inline parameter types may be specified (see )

Tip. Always using parentheses even for single-parameter arrow functions can avoid situations where adding parameters, but forgetting to add parentheses, may result in parseable code which no longer works as intended

The right-hand side of the arrow contains the body of the function. By default the body is a block statement (zero or more statements surrounded by curly braces). The body may also be an implicitly returned single expression if either. the program logic requires returning a value, or the

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
20 operator precedes a single function or method call (using
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
20 ensures
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
45 is returned, prevents leaking values, and communicates intent). The single expression form is preferred if it improves readability (e. g. , for short or simple expressions)

ví dụ

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
0

không được phép

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
1

5. 5. 4 Generators

Generators enable a number of useful abstractions and may be used as needed

When defining generator functions, attach the

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
31 to the
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
01 keyword when present, and separate it with a space from the name of the function. When using delegating yields, attach the
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
31 to the
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
26 keyword

Ví dụ

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
2

5. 5. 5 Parameter and return types

Function parameters and return types should usually be documented with JSDoc annotations. See for more information

5. 5. 5. 1 Default parameters

Optional parameters are permitted using the equals operator in the parameter list. Optional parameters must include spaces on both sides of the equals operator, be named exactly like required parameters (i. e. , not prefixed with

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
26), use the
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
27 suffix in their JSDoc type, come after required parameters, and not use initializers that produce observable side effects. All optional parameters for concrete functions must have default values, even if that value is
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
45. In contrast to concrete functions, abstract and interface methods must omit default parameter values

Ví dụ

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
3

Use default parameters sparingly. Prefer destructuring (as in ) to create readable APIs when there are more than a small handful of optional parameters that do not have a natural order

Note. Unlike Python's default parameters, it is okay to use initializers that return new mutable objects (such as

goog.module('search.urlHistory.UrlHistoryService');
81 or
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
52) because the initializer is evaluated each time the default value is used, so a single object won't be shared across invocations

Tip. While arbitrary expressions including function calls may be used as initializers, these should be kept as simple as possible. Avoid initializers that expose shared mutable state, as that can easily introduce unintended coupling between function calls

5. 5. 5. 2 Rest parameters

Use a rest parameter instead of accessing

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
31. Rest parameters are typed with a
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
51 prefix in their JSDoc. The rest parameter must be the last parameter in the list. There is no space between the
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
51 and the parameter name. Do not name the rest parameter
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
34. Never name a local variable or parameter
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
31, which confusingly shadows the built-in name

Ví dụ

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
4

5. 5. 6 Generics

Declare generic functions and methods when necessary with

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
36 in the JSDoc above the function or method definition

5. 5. 7 Spread operator

Function calls may use the spread operator (

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
51). Prefer the spread operator to
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
38 when an array or iterable is unpacked into multiple parameters of a variadic function. There is no space after the
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
51

Ví dụ

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
5

5. 6 String literals

5. 6. 1 Use single quotes

Ordinary string literals are delimited with single quotes (

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
40), rather than double quotes (
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
41)

Tip. if a string contains a single quote character, consider using a template string to avoid having to escape the quote

Ordinary string literals may not span multiple lines

5. 6. 2 Template literals

Use template literals (delimited with

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
42) over complex string concatenation, particularly if multiple string literals are involved. Template literals may span multiple lines

If a template literal spans multiple lines, it does not need to follow the indentation of the enclosing block, though it may if the added whitespace does not matter

Ví dụ

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
6

5. 6. 3 No line continuations

Do not use line continuations (that is, ending a line inside a string literal with a backslash) in either ordinary or template string literals. Even though ES5 allows this, it can lead to tricky errors if any trailing whitespace comes after the slash, and is less obvious to readers

không được phép

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
7

Thay 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';
8

5. 7 Number literals

Numbers may be specified in decimal, hex, octal, or binary. Use exactly

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
43,
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
44, and
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
45 prefixes, with lowercase letters, for hex, octal, and binary, respectively. Never include a leading zero unless it is immediately followed by
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
46,
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
47, or
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
48

5. 8 Control structures

5. 8. 1 For loops

With ES6, the language now has three different kinds of

goog.module('search.urlHistory.UrlHistoryService');
75 loops. All may be used, though
goog.module('search.urlHistory.UrlHistoryService');
75-
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
25 loops should be preferred when possible

goog.module('search.urlHistory.UrlHistoryService');
75-
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
24 loops may only be used on dict-style objects (see ), and should not be used to iterate over an array.
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
54 should be used in
goog.module('search.urlHistory.UrlHistoryService');
75-
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
24 loops to exclude unwanted prototype properties. Prefer
goog.module('search.urlHistory.UrlHistoryService');
75-
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
25 and
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
59 over
goog.module('search.urlHistory.UrlHistoryService');
75-
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
24 when possible

5. 8. 2 Exceptions

Exceptions are an important part of the language and should be used whenever exceptional cases occur. Always throw

goog.module('search.urlHistory.UrlHistoryService');
63s or subclasses of
goog.module('search.urlHistory.UrlHistoryService');
63. never throw string literals or other objects. Always use
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
64 when constructing an
goog.module('search.urlHistory.UrlHistoryService');
63

This treatment extends to

goog.module('search.urlHistory.UrlHistoryService');
65 rejection values as
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
67 is equivalent to
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
68 in async functions

Custom exceptions provide a great way to convey additional error information from functions. They should be defined and used wherever the native

goog.module('search.urlHistory.UrlHistoryService');
63 type is insufficient

Prefer throwing exceptions over ad-hoc error-handling approaches (such as passing an error container reference type, or returning an object with an error property)

Rất hiếm khi đúng khi không làm gì để đáp lại một ngoại lệ bị bắt. When it truly is appropriate to take no action whatsoever in a catch block, the reason this is justified is explained in a comment

import './sideeffects.js';

import * as goog from '../closure/goog/goog.js';
import * as parent from '../parent.js';

import {name} from './sibling.js';
9

không được phép

import '../directory/file';
0

Mẹo. Không giống như ở một số ngôn ngữ khác, các mẫu như trên đơn giản là không hoạt động vì điều này sẽ bắt lỗi do

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
70 đưa ra. Sử dụng
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
71 để thay thế

5. 8. 3 Switch statements

Lưu ý thuật ngữ. Bên trong dấu ngoặc nhọn của 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 (hoặc là

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
72 hoặc là
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 mùa thu. commented

Within a switch block, each statement group either terminates abruptly (with a

goog.module('search.urlHistory.UrlHistoryService');
89,
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
21 or
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
22n exception), or is marked with a comment to indicate that execution will or might continue into the next statement group. Bất kỳ nhận xét nào truyền đạt ý tưởng về sự thất bại là đủ (thường là
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
77). This special comment is not required in the last statement group of the switch block

Ví dụ

import '../directory/file';
1
5. 8. 3. 2 The
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
78 case is present

Each switch statement includes a

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
78 statement group, even if it contains no code. The
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
78 statement group must be last

5. 9 this

Only use

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
66 in class constructors and methods, in arrow functions defined within class constructors and methods, or in functions that have an explicit
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
82 declared in the immediately-enclosing function’s JSDoc

Never use

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
66 to refer to the global object, the context of an
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
84, the target of an event, or unnecessarily
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
85ed or
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
86ed functions

5. 10 Equality Checks

Use identity operators (

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
87/
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
88) except in the cases documented below

5. 10. 1 Exceptions Where Coercion is Desirable

Catching both

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
89 and
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
45 values

import '../directory/file';
2

5. 11 Disallowed features

5. 11. 1 with

Do not use the

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
91 keyword. It makes your code harder to understand and has been banned in strict mode since ES5

5. 11. 2 Dynamic code evaluation

Do not use

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
84 or the
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
93 constructor (except for code loaders). These features are potentially dangerous and simply do not work in CSP environments

5. 11. 3 Automatic semicolon insertion

Always terminate statements with semicolons (except function and class declarations, as noted above)

5. 11. 4 Non-standard features

Do not use non-standard features. This includes old features that have been removed (e. g. ,

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
94), new features that are not yet standardized (e. g. , the current TC39 working draft, proposals at any stage, or proposed but not-yet-complete web standards), or proprietary features that are only implemented in some browsers. Use only features defined in the current ECMA-262 or WHATWG standards. (Note that projects writing against specific APIs, such as Chrome extensions or Node. js, can obviously use those APIs). Non-standard language “extensions” (such as those provided by some external transpilers) are forbidden

5. 11. 5 Wrapper objects for primitive types

Never use

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
64 on the primitive object wrappers (
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), nor include them in type annotations

không được phép

import '../directory/file';
3

The wrappers may be called as functions for coercing (which is preferred over using

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 or concatenating the empty string) or creating symbols

Ví dụ

import '../directory/file';
4

5. 11. 6 Modifying builtin objects

Never modify builtin types, either by adding methods to their constructors or to their prototypes. Avoid depending on libraries that do this. Note that the JSCompiler’s runtime library will provide standards-compliant polyfills where possible; nothing else may modify builtin objects

Do not add symbols to the global object unless absolutely necessary (e. g. required by a third-party API)

5. 11. 7 Omitting
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 when invoking a constructor

Never invoke a constructor in a

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
64 statement without using parentheses
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

không được phép

import '../directory/file';
5

Use instead

import '../directory/file';
6

Omitting parentheses can lead to subtle mistakes. These two lines are not equivalent

import '../directory/file';
7

6 Naming

6. 1 Rules common to all identifiers

Identifiers use only ASCII letters and digits, and, in a small number of cases noted below, underscores and very rarely (when required by frameworks like Angular) dollar signs

Give as descriptive a name as possible, within reason. Do not worry about saving horizontal space as it is far more important to make your code immediately understandable by a new reader. Do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word

import '../directory/file';
8

không được phép

import '../directory/file';
9

6. 2 Rules by identifier type

6. 2. 1 Package names

Package names are all

goog.module('search.urlHistory.UrlHistoryService');
01. For 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};
05, but not
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 or
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 Class names

Class, interface, record, and typedef names are written in

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. Unexported classes are simply locals. they are not marked
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 and therefore are not named with a trailing underscore

Type names are typically nouns or noun phrases. For 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};
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, or
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. Additionally, interface names may sometimes be adjectives or adjective phrases instead (for 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};
13)

6. 2. 3 Method names

Method names are written in

goog.module('search.urlHistory.UrlHistoryService');
01. Names for
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 methods must end with a trailing underscore

Method names are typically verbs or verb phrases. For 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};
16 or
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. Getter and setter methods for properties are never required, but if they are used they should be named
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 (or optionally
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 or
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 for booleans), or
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 for setters

Underscores may also appear in JsUnit test method names to separate logical components of the name. One typical pattern is

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, for 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};
23. There is no One Correct Way to name test methods

6. 2. 4 Enum names

Enum names are written in

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, similar to classes, and should generally be singular nouns. Individual items within the enum are named in
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 Constant names

Constant names use

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. all uppercase letters, with words separated by underscores. There is no reason for a constant to be named with a trailing underscore, since private static properties can be replaced by (implicitly private) module locals

6. 2. 5. 1 Definition of “constant”

Every constant is a

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96 static property or a module-local
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
33 declaration, but not all
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
96 static properties and module-local
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
33s are constants. Before choosing constant case, consider whether the field really feels like a deeply immutable constant. For example, if any of that instance's observable state can change, it is almost certainly not a constant. Merely intending to never mutate the object is generally not enough

ví dụ

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
00

Constants’ names are typically nouns or noun phrases

6. 2. 5. 2 Local aliases

Local aliases should be used whenever they improve readability over fully-qualified names. Follow the same rules as

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74s (), maintaining the last part of the aliased name. Aliases may also be used within functions. Aliases must be
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
33

ví dụ

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
01

6. 2. 6 Non-constant field names

Non-constant field names (static or otherwise) are written in

goog.module('search.urlHistory.UrlHistoryService');
01, with a trailing underscore for private fields

These names are typically nouns or noun phrases. For 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};
34 or
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 Parameter names

Parameter names are written in

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

Không nên sử dụng tên tham số một ký tự trong các phương thức công khai

Exception. 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};
37. This exception does not apply to any other identifiers (e. g. local variables or properties)

6. 2. 8 Local variable names

Local variable names are written in

goog.module('search.urlHistory.UrlHistoryService');
01, except for module-local (top-level) constants, as described above. Constants in function scopes are still named in
goog.module('search.urlHistory.UrlHistoryService');
01. Note that
goog.module('search.urlHistory.UrlHistoryService');
01 is used even if the variable holds a constructor

6. 2. 9 Template parameter names

Template parameter names should be concise, single-word or single-letter identifiers, and must be all-caps, such as

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 or
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 Module-local names

Module-local names that are not exported are implicitly private. They are not marked

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
94 and do not end in an underscore. This applies to classes, functions, variables, constants, enums, and other module-local identifiers

6. 3 Camel case. defined

Sometimes there is more than one reasonable way to convert an English phrase into camel case, such as when acronyms or unusual constructs like IPv6 or iOS are present. To improve predictability, Google Style specifies the following (nearly) deterministic scheme

Beginning with the prose form of the name

  1. Convert the phrase to plain ASCII and remove any apostrophes. For example, Müller's algorithm might become Muellers algorithm
  2. Divide this result into words, splitting on spaces and any remaining punctuation (typically hyphens)
    1. Recommended. if any word already has a conventional camel case appearance in common usage, split this into its constituent parts (e. g. , AdWords becomes ad words). Note that a word such as iOS is not really in camel case per se; it defies any convention, so this recommendation does not apply
  3. Now lowercase everything (including acronyms), then uppercase only the first character of
    1. … each word, to yield upper camel case, or
    2. … each word except the first, to yield lower camel case
  4. Finally, join all the words into a single identifier

Note that the casing of the original words is almost entirely disregarded

ví dụ

Prose formCorrectIncorrectXML HTTP requestXmlHttpRequestXMLHTTPRequestnew customer IDnewCustomerIdnewCustomerIDinner stopwatchinnerStopwatchinnerStopWatchsupports IPv6 on iOS?supportsIpv6OnIossupportsIPv6OnIOSYouTube importerYouTubeImporterYoutubeImporter*

*Acceptable, but not recommended

Note. Some words are ambiguously hyphenated in the English language. for example nonempty and non-empty are both correct, so the method names checkNonempty and checkNonEmpty are likewise both correct

7 JSDoc

JSDoc is used on all classes, fields, and methods

7. 1 General form

The basic formatting of JSDoc blocks is as seen in this example

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
02

or in this single-line example

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
03

If a single-line comment overflows into multiple lines, it must use the multi-line style with

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 and
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 on their own lines

Many tools extract metadata from JSDoc comments to perform code validation and optimization. As such, these comments must be well-formed

7. 2 Markdown

JSDoc is written in Markdown, though it may include HTML when necessary

Note that tools that automatically extract JSDoc (e. g. JsDossier) will often ignore plain text formatting, so if you did this

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
04

it would come out like this

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
05

Instead, write a Markdown list

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
06

Google style allows a subset of JSDoc tags. See for the complete list. Most tags must occupy their own line, with the tag at the beginning of the line

không được phép

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
07

Simple tags that do not require any additional data (such as

/* 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) may be combined onto the same line, along with an optional type when appropriate

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
08

There is no hard rule for when to combine tags, or in which order, but be consistent

For general information about annotating types in JavaScript see Annotating JavaScript for the Closure Compiler and Types in the Closure Type System

7. 4 Line wrapping

Line-wrapped block tags are indented four spaces. Wrapped description text may be lined up with the description on previous lines, but this horizontal alignment is discouraged

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
09

Do not indent when wrapping 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};
50 or
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
70 description

Một tệp có thể có tổng quan về tệp cấp cao nhất. A copyright notice , author information, and default are optional. File overviews are generally recommended whenever a file consists of more than a single class definition. The top level comment is designed to orient readers unfamiliar with the code to what is in this file. If present, it may provide a description of the file's contents and any dependencies or compatibility information. Wrapped lines are not indented

Ví dụ

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
10

Classes, interfaces and records must be documented with a description and any template parameters, implemented interfaces, visibility, or other appropriate tags. The class description should provide the reader with enough information to know how and when to use the class, as well as any additional considerations necessary to correctly use the class. Textual descriptions may be omitted on the constructor.

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 and
goog.module('search.urlHistory.UrlHistoryService');
88 annotations are not used with the
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
97 keyword unless the class is being used to declare an
goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
05 or it extends a generic class

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
11

All enums and typedefs must be documented with appropriate JSDoc tags (

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 or
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
73) on the preceding line. Public enums and typedefs must also have a description. Individual enum items may be documented with a JSDoc comment on the preceding line

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
12

Typedefs are useful for defining short record types, or aliases for unions, complex functions, or generic types. Typedefs should be avoided for record types with many fields, since they do not allow documenting individual fields, nor using templates or recursive references. For large record types, prefer

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
06

In methods and named functions, parameter and return types must be documented, except in the case of same-signature

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, where all types are omitted. The
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
66 type should be documented when necessary. Return type may be omitted if the function has no non-empty
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
21 statements

Method, parameter, and return descriptions (but not types) may be omitted if they are obvious from the rest of the method’s JSDoc or from its signature

Method descriptions begin with a verb phrase that describes what the method does. This phrase is not an imperative sentence, but instead is written in the third person, as if there is an implied This method . before it

If a method overrides a superclass method, it must include an

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 annotation. Overridden methods inherit all JSDoc annotations from the super class method (including visibility annotations) and they should be omitted in the overridden method. However, if any type is refined in type annotations, all
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 and
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 annotations must be specified explicitly

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
13

If you only need to document the param and return types of a function, you may optionally use inline JSDocs in the function's signature. These inline JSDocs specify the return and param types without tags

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
14

If you need descriptions or tags, use a single JSDoc comment above the method. For example, methods which return values need 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};
64 tag

/* 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';
16

In anonymous functions annotations are generally optional. If the automatic type inference is insufficient or explicit annotation improves readability, then annotate param and return types like this

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
17

For function type expressions, see

Property types must be documented. The description may be omitted for private properties, if name and type provide enough documentation for understanding the code

Publicly exported constants are commented the same way as properties

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
18

7. 10 Type annotations

Type annotations are found on

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, and
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 tags, and optionally on
/* 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, and any visibility tags. Các chú thích loại được đính kèm với các thẻ JSDoc phải luôn được đặt trong dấu ngoặc nhọn

7. 10. 1 Nullability

The type system defines modifiers

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 and
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 for non-null and nullable, respectively. These modifiers must precede the type

Nullability modifiers have different requirements for different types, which fall into two broad categories

  1. Type annotations for primitives (
    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};
    
    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,
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    45,
    goog.module('my.test.helpers');
    goog.module.declareLegacyNamespace();
    goog.setTestOnly();
    
    89) and literals (
    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};
    
    80 and
    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) are always non-nullable by default. Use the
    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 modifier to make it nullable, but omit the redundant
    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
  2. Reference types (generally, anything in
    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, including
    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};
    
    85) refer to a class, enum, record, or typedef defined elsewhere. Since these types may or may not be nullable, it is impossible to tell from the name alone whether it is nullable or not. Always use explicit
    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 and
    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 modifiers for these types to prevent ambiguity at use sites

Bad

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
19

Tốt

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
20

7. 10. 2 loại phôi

Trong trường hợp trình biên dịch không suy luận chính xác loại biểu thức và các hàm xác nhận trong goog. khẳng định 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 là bắt buộc

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
21

7. 10. 3 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ể thực hiện công việc tốt hơn và giúp người đọc dễ dàng hiểu mã làm gì hơn

Bad

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
22

Tốt

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
23

Các trường hợp không nên sử dụng tham số mẫu

  • goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    50 được sử dụng cho phân cấp kiểu và không phải là cấu trúc giống như bản đồ

7. 10. 4 Biểu thức kiểu hàm

Lưu ý thuật ngữ. biểu thức loại hàm đề cập đến một chú thích loại cho các loại hàm với từ khóa

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
01 trong chú thích (xem ví dụ bên dưới)

Khi định nghĩa hàm được đưa ra, không sử dụng biểu thức kiểu hàm. Chỉ định tham số và kiểu 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 chú thích nội tuyến (xem phần ). Điều này bao gồm các hàm ẩn danh và các hàm được xác định và gán cho một const (trong đó hàm jsdoc xuất hiện phía trên toàn bộ biểu thức gán)

Các biểu thức kiểu hàm 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. Cũng sử dụng nó cho các biến hoặc thuộc tính của kiểu hàm, nếu chúng không được khởi tạo ngay với định nghĩa hàm

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
24

Khi sử dụng biểu thức kiểu hàm, luôn chỉ định rõ ràng kiểu trả về. Mặt khác, loại trả về mặc định là không xác định (_______52_______73), dẫn đến hành vi kỳ lạ và không mong muốn, và hiếm khi là điều thực sự mong muốn

Xấu - gõ lỗi, nhưng không đưa ra cảnh báo

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
25

Tốt

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
26

7. 10. 5 khoảng trắng

Trong một chú thích loại, cần có một dấu cách hoặc ngắt dòng sau mỗi dấu phẩy hoặc dấu hai chấm. Các ngắt dòng bổ sung có thể được chèn vào để cải thiện khả năng đọc hoặc tránh vượt quá giới hạn cột. Những dấu ngắt này nên được chọn và thụt lề theo hướng dẫn hiện hành (e. g. Và ). Không có khoảng trắng nào khác được phép trong chú thích loại

Tốt

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
27

Bad

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
28

7. 11 chú thích 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 chức năng hay ở cấp cao nhất của mô-đun. Tất cả tên
/* 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

8 chính sách

8. 1 Sự cố không được chỉ định bởi Google Style. Hãy nhất quán

Đối với bất kỳ câu hỏi về phong cách nào không được giải quyết dứt khoát bởi thông số kỹ thuật này, hãy ưu tiên thực hiện những gì mà mã khác trong cùng một tệp đang thực hiện. 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ác dự án càng nhiều càng tốt 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 chắc tại sao lại xuất hiện cảnh báo, hãy yêu cầu trợ giúp

Khi bạn hiểu cảnh báo, hãy thử các giải pháp sau theo thứ tự

  1. Đầu tiên, sửa chữ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 cách khác để hoàn thành nhiệm vụ tránh hoàn toàn tình huống
  2. Nếu không, hãy xác định xem đó có phải là báo động giả không. Nếu bạn tin rằng cảnh báo không hợp lệ và mã thực sự an toàn và chính xác, hãy thêm nhận xét để thuyết phục người đọc về sự thật này và áp dụng chú thích
    /** @const {number} */
    exports.CONSTANT_ONE = 1;
    
    /** @const {string} */
    exports.CONSTANT_TWO = 'Another constant';
    
    02
  3. Nếu không, hãy để lại nhận xét TODO. Đây là một phương sách cuối cùng. Nếu bạn làm điều này, đừng chặn cảnh báo. Cảnh báo sẽ hiển thị cho đến khi nó có thể được xử lý đúng cách

8. 2. 3 Loại bỏ cảnh báo ở phạm vi hợp lý hẹp nhất

Các cảnh báo bị loại bỏ ở 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 thức rất nhỏ. Thường thì một biến hoặc phương thức được trích xuất chỉ vì lý do đó

Ví dụ

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
29

Ngay cả một số lượng lớn các biện pháp ngăn chặn trong một lớp vẫn tốt hơn là làm mù cả lớp trước kiểu cảnh báo này

Đánh dấu các phương thức, lớp hoặc giao diện không dùng nữa bằng chú thích

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
03. Nhận xét không dùng nữa phải bao gồm hướng dẫn đơn giản, rõ ràng để mọi người khắc phục trang web cuộc gọi của họ

8. 4 Code not in Google Style

You will occasionally encounter files in your codebase that are not in proper Google Style. These may have come from an acquisition, or may have been written before Google Style took a position on some issue, or may be in non-Google Style for any other reason

8. 4. 1 Reformatting existing code

When updating the style of existing code, follow these guidelines

  1. It is not required to change all existing code to meet current style guidelines. Reformatting existing code is a trade-off between code churn and consistency. Style rules evolve over time and these kinds of tweaks to maintain compliance would create unnecessary churn. However, if significant changes are being made to a file it is expected that the file will be in Google Style
  2. Be careful not to allow opportunistic style fixes to muddle the focus of a CL. If you find yourself making a lot of style changes that aren’t critical to the central focus of a CL, promote those changes to a separate CL

8. 4. 2 Newly added code. use Google Style

Brand new files use Google Style, regardless of the style choices of other files in the same package

When adding new code to a file that is not in Google Style, reformatting the existing code first is recommended, subject to the advice in

If this reformatting is not done, then new code should be as consistent as possible with existing code in the same file, but must not violate the style guide

8. 5 Local style rules

Teams and projects may adopt additional style rules beyond those in this document, but must accept that cleanup changes may not abide by these additional rules, and must not block such cleanup changes due to violating any additional rules. Beware of excessive rules which serve no purpose. The style guide does not seek to define style in every possible scenario and neither should you

8. 6 Generated code. mostly exempt

Source code generated by the build process is not required to be in Google Style. However, any generated identifiers that will be referenced from hand-written source code must follow the naming requirements. As a special exception, such identifiers are allowed to contain underscores, which may help to avoid conflicts with hand-written identifiers

9 Appendices

9. 1 JSDoc tag reference

JSDoc serves multiple purposes in JavaScript. In addition to being used to generate documentation it is also used to control tooling. The best known are the Closure Compiler type annotations

9. 1. 1 Type annotations and other Closure Compiler annotations

Documentation for JSDoc used by the Closure Compiler is described in Annotating JavaScript for the Closure Compiler and Types in the Closure Type System

9. 1. 2 Documentation annotations

In addition to the JSDoc described in Annotating JavaScript for the Closure Compiler the following tags are common and well supported by various documentation generation tools (such as JsDossier) for purely documentation purposes

You may also see other types of JSDoc annotations in third-party code. These annotations appear in the JSDoc Toolkit Tag Reference but are not considered part of valid Google style

9. 1. 2. 1
/** @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 nên dùng

Not recommended

Syntax.

/** @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';
30

Tài liệu về 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. The
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
05 tag is used by the unit test dashboard to determine who owns the test results

9. 1. 2. 2
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
09

cú 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';
31

Cho biết những lỗi mà chức năng kiểm tra đã cho kiểm tra hồi quy

Mỗi lỗi nên có dòng

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
09 riêng, để giúp việc tìm kiếm các bài kiểm tra hồi quy trở nên dễ dàng nhất có thể

9. 1. 2. 3
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
12 - Không dùng nữa. Không được dùng

không dùng nữa. Không được dùng. Sử dụng backticks Markdown để thay thế

cú pháp.

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
13

Trong 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';
32

Cho biết 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

9. 1. 2. 4
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

cú 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
9. 1. 2. 5
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
18

cú pháp.

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
19

Thẻ này được sử dụng để tạo 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';
34

Ghi chú 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, hãy luôn sử dụng cú pháp liên kết của Markdown để thay thế

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
35
9. 1. 2. 6
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
20

cú 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';
36

Tham chiếu tra cứu đến một hàm hoặc phương thức lớp khác

9. 1. 2. 7
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
22

cú 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 phần tổng quan về tệp để cho biết trình duyệt nào được tệp hỗ trợ

9. 1. 3 Chú thích cụ thể của khung

Các chú thích sau đây dành riêng cho một khung cụ thể

9. 1. 3. 1
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
24 cho Góc 1
9. 1. 3. 2
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
25 cho Polyme

https. //github. com/google/closure-compiler/wiki/Polymer-Pass

9. 1. 4 Lưu ý về chú thích Trình biên dịch đóng cửa tiêu chuẩn

Các thẻ sau từng là tiêu chuẩn nhưng hiện không được dùng nữa

9. 1. 4. 1
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
26 - Không dùng nữa. Không được dùng

không dùng nữa. Không được dùng. 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};
49 và/hoặc
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
87 thay thế

9. 1. 4. 2
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
29 - Không dùng nữa. Không được dùng

không dùng nữa. Không được dùng. 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};
59 để thay thế

9. 2 Quy tắc phong cách thường bị hiểu lầm

Đây là tập hợp các sự kiện ít được biết đến hoặc thường bị hiểu lầm về Google Style cho JavaScript. (Sau đây là những tuyên bố đúng; đây không phải là danh sách những huyền thoại. )

  • Không yêu cầu tuyên bố bản quyền cũng như tín dụng
    /** @const {number} */
    exports.CONSTANT_ONE = 1;
    
    /** @const {string} */
    exports.CONSTANT_TWO = 'Another constant';
    
    04 trong tệp nguồn. (Cả hai đều không được khuyến nghị rõ ràng. )
  • Không có quy tắc cứng và nhanh nào quản lý cách sắp xếp thứ tự các thành viên của một lớp ()
  • Các khối rỗng thường có thể được biểu diễn chính xác dưới dạng
    goog.module('search.urlHistory.UrlHistoryService');
    
    81, như được trình bày chi tiết trong ()
  • Chỉ thị chính của line-wrapping là. thích ngắt ở cấp độ cú pháp cao hơn ()
  • Các ký tự không phải ASCII được cho phép ở dạng chuỗi ký tự, 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 lối thoát Unicode tương đương ()

Các công cụ sau 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 cửa

Chương trình này thực hiện kiểm tra kiểu và các kiểm tra khác, tối ưu hóa và các chuyển đổi khác (chẳng hạn như giảm mã ECMAScript 6 xuống ECMAScript 5)

9. 3. 2
goog.module('search.urlHistory.UrlHistoryService');
71

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ố phương pháp định dạng nâng cao khả năng đọc không bắt buộc nhưng thường xuyên. Đầu ra do

goog.module('search.urlHistory.UrlHistoryService');
71 tạo ra tuân theo hướng dẫn về phong cách

goog.module('search.urlHistory.UrlHistoryService');
71 không bắt buộc. 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 đó; . Tuy nhiên, các cây con có thể chọn tham gia thực thi như vậy cục bộ

9. 3. 3 Đóng trình biên dịch linter

Chương trình này kiểm tra một loạt các bước sai và chống mẫu

9. 3. 4 Khung tuân thủ

JS Conformance Framework là một công cụ nằm trong Closure Compiler cung cấp cho các nhà phát triển một phương tiện đơn giản để chỉ định một tập hợp các kiểm tra bổ sung sẽ được chạy đối 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 lệnh gọi đến một chức năng nhất định hoặc thiếu thông tin loại (không xác định)

Các quy tắc này thường được sử dụng để thực thi các hạn chế quan trọng (chẳng hạn như xác định toàn cầu, có thể phá vỡ cơ sở mã) và các mẫu bảo mật (chẳng hạn như sử dụng

goog.module('my.test.helpers');
goog.module.declareLegacyNamespace();
goog.setTestOnly();
84 hoặc gán cho ____53_______37) hoặc để cải thiện chất lượng mã một cách lỏng lẻo hơn

Để biết thêm thông tin, hãy xem tài liệu chính thức về Khung tuân thủ JS

9. 4 Ngoại lệ cho các nền tảng cũ

9. 4. 1. Khái quát chung

Phần này mô tả các ngoại lệ và quy tắc bổ sung cần tuân theo khi cú pháp ECMAScript 6 hiện đại không có sẵn cho tác giả mã. Các ngoại lệ đối với kiểu được đề xuất là bắt buộc khi không thể sử dụng cú pháp ECMAScript 6 và được nêu tại đây

  • Cho phép sử dụng các khai báo
    goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
    goog.module('foo.bar.baz');
    
    37
  • Cho phép sử dụng
    goog.module('my.test.helpers');
    goog.module.declareLegacyNamespace();
    goog.setTestOnly();
    
    31
  • Cho phép tham số tùy chọn không có giá trị mặc định

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 khai báo
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
37 KHÔNG nằm trong phạm vi khối

Các khai báo

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
37 nằm trong phạm vi bắt đầu của hàm, tập lệnh hoặc mô-đun kèm theo gần nhất, điều này có thể gây ra hành vi không mong muốn, đặc biệt là với các hàm đóng tham chiếu các khai báo
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
37 bên trong các vòng lặp. Đoạn mã sau đưa ra một ví dụ

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
38
9. 4. 2. 2 Khai báo các biến càng gần với lần sử dụng đầu tiên càng tốt

Mặc dù các khai báo

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
37 nằm trong phạm vi bắt đầu của hàm kèm theo, nhưng các khai báo
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
37 phải càng gần với lần sử dụng đầu tiên càng tốt, vì mục đích dễ đọ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';
39
9. 4. 2. 3 Sử dụng @const cho các biến hằng

Đối với các khai báo toàn cục mà 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ó, 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 bằng @const thay thế (điều này là tùy chọn đối với các biến cục bộ)

9. 4. 3 Không sử dụng khai báo hàm phạm vi khối

Đừng làm điều này

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
40

Mặc dù hầu hết các máy ảo JavaScript được triển khai trước khi ECMAScript 6 hỗ trợ khai báo hàm trong các khối nhưng nó không được chuẩn hóa. Việc triển khai không nhất quán với nhau và với hành vi ECMAScript 6 tiêu chuẩn hiện nay để khai báo hàm phạm vi khối. ECMAScript 5 trở về trước chỉ cho phép khai báo hàm trong danh sách câu lệnh gốc của tập lệnh hoặc hàm và cấm rõ ràng chú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 một __

goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
goog.module('foo.bar.baz');
_37 được khởi tạo với một biểu thức hàm để xác định một hàm trong một khối

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
41

9. 4. 4 Quản lý phụ thuộc với
goog.module('search.urlHistory.UrlHistoryService');
18/
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74

9. 4. 4. 1. Tóm tắt

CẢNH BÁO.

goog.module('search.urlHistory.UrlHistoryService');
18 quản lý phụ thuộc không được dùng nữa. 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. Các quy tắc sau đây chỉ dành cho các tệp
goog.module('search.urlHistory.UrlHistoryService');
18 đã có từ trước

  • Đặt tất cả
    goog.module('search.urlHistory.UrlHistoryService');
    
    18 đầu tiên,
    /* Poor: the reader has no idea what character this is. */
    const units = '\u03bcs';
    
    74 giây. Tách cung cấp khỏi yêu cầu bằng một dòng trống
  • Sắp xếp các mục theo thứ tự bảng chữ cái (viết hoa trước)
  • Không bọ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. Vượt quá 80 cột nếu cần
  • Chỉ cung cấp các biểu tượng cấp cao nhất

goog.module('search.urlHistory.UrlHistoryService');
18 câu lệnh nên được nhóm lại với nhau và đặt ở vị trí đầu tiên. Tất cả các câu lệnh
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74 phải tuân theo. Hai danh sách phải được phân tách bằng một dòng trống

Tương tự như câu lệnh nhập bằng các ngôn ngữ khá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 phải được viết trên 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 nên được sắp xếp theo thứ tự bảng chữ cái, với các chữ cái viết hoa đến trước

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
42

Tất cả các thành viên được xác định trên một lớp phải ở trong cùng một tệp. Chỉ nên cung cấp các lớp cấp cao nhất trong một tệp chứa nhiều thành viên được định nghĩa trên cùng một lớp (e. g. enums, các 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';
43

Không phải cái này

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
44

Thành viên trên 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';
45
9. 4. 4. 2 Bí danh với
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64

CẢNH BÁO.

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 không được dùng nữa. 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ó sử dụng
/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 hiện tại

/** @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 được đặt tên trong mã bằng cách sử dụng quản lý phụ thuộc
goog.module('search.urlHistory.UrlHistoryService');
18/
/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
74

Chỉ có thể thêm một lệnh gọi

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
64 cho mỗi tệp. Luôn đặt nó trong phạm vi toàn cầu

Lời gọi

/** @const {number} */
exports.CONSTANT_ONE = 1;

/** @const {string} */
exports.CONSTANT_TWO = 'Another constant';
72 mở đầu phải được đặt trước chính xác một dòng trống và theo sau mọi câu lệnh
goog.module('search.urlHistory.UrlHistoryService');
18, 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. Lệnh gọi phải được đóng ở 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 phần kết thúc của phạm vi. Tách nhận xét khỏi dấu chấm phẩy bằng hai dấu cách

Tương tự như không gian tên C++, không thụt lề dưới 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 đối tượng khác (e. g. , hầu hết các hàm tạo, enum và không gian tên). Đừng làm điều này (xem bên dưới để biết cách đặt bí danh cho hàm tạo)

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
46

Tên phải giống với thuộc tính cuối cùng của toàn cầu mà chúng đang đặt bí danh

/* Poor: the reader has no idea what character this is. */
const units = '\u03bcs';
47
9. 4. 4. 3
goog.module('search.urlHistory.UrlHistoryService');
25

Ưu tiên 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ỡ sự phụ thuộc vòng 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 một không gian tên trước khi nó được xác định

goog.module('search.urlHistory.UrlHistoryService');
25 vẫn có thể được sử dụng trong mã kế thừa để phá vỡ các tham chiếu vòng tròn trải rộng 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 điều đó

Các câu lệnh của

goog.module('search.urlHistory.UrlHistoryService');
25 phải tuân theo các quy tắc về văn phong giống như của
/* 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 câu lệnh
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