Skip to main content

编码风格

¥Coding Style

这些是 Electron 编码的风格指南。

¥These are the style guidelines for coding in Electron.

你可以运行 npm run lint 以显示 cpplint 和 eslint 检测到的任何样式问题。

¥You can run npm run lint to show any style issues detected by cpplint and eslint.

通用代码​

¥General Code

  • 以换行符结束文件。

    ¥End files with a newline.

  • 地点要求按以下顺序：

    ¥Place requires in the following order:

    • 内置 Node 模块（如 path）

      ¥Built in Node Modules (such as path)

    • 内置 Electron 模块（如 ipc、app）

      ¥Built in Electron Modules (such as ipc, app)

    • 本地模块（使用相对路径）

      ¥Local Modules (using relative paths)

  • 按以下顺序放置类属性：

    ¥Place class properties in the following order:

    • 类方法和属性（以 @ 开头的方法）

      ¥Class methods and properties (methods starting with a @)

    • 实例方法和属性

      ¥Instance methods and properties

  • 避免依赖平台的代码：

    ¥Avoid platform-dependent code:

    • 使用 path.join() 连接文件名。

      ¥Use path.join() to concatenate filenames.

    • 当你需要引用临时目录时，请使用 os.tmpdir() 而不是 /tmp。

      ¥Use os.tmpdir() rather than /tmp when you need to reference the temporary directory.

  • 在函数末尾显式返回时使用普通 return。

    ¥Using a plain return when returning explicitly at the end of a function.

    • 不是 return null、return undefined、null 或 undefined

      ¥Not return null, return undefined, null or undefined

C++ 和 Python​

¥C++ and Python

对于 C++ 和 Python，我们遵循 Chromium 的 编码风格。还有一个脚本 script/cpplint.py 用于检查所有文件是否符合要求。

¥For C++ and Python, we follow Chromium's Coding Style. There is also a script script/cpplint.py to check whether all files conform.

我们现在使用的 Python 版本是 Python 3.9。

¥The Python version we are using now is Python 3.9.

C++ 代码使用了大量 Chromium 的抽象和类型，因此建议熟悉它们。Chromium 的 重要的抽象和数据结构 文档是一个很好的起点。该文档提到了一些特殊类型、作用域类型（超出作用域时自动释放内存）、日志机制等。

¥The C++ code uses a lot of Chromium's abstractions and types, so it's recommended to get acquainted with them. A good place to start is Chromium's Important Abstractions and Data Structures document. The document mentions some special types, scoped types (that automatically release their memory when going out of scope), logging mechanisms etc.

文档​

¥Documentation

  • 编写 remark Markdown 风格。

    ¥Write remark markdown style.

你可以运行 npm run lint:docs 以确保文档更改的格式正确。

¥You can run npm run lint:docs to ensure that your documentation changes are formatted correctly.

JavaScript​

  • 编写 standard JavaScript 风格。

    ¥Write standard JavaScript style.

  • 文件名应使用 - 而不是 _ 连接，例如 file-name.js 而不是 file_name.js，因为在 atom/atom 中模块名称通常采用 module-name 形式。此规则仅适用于 .js 文件。

    ¥File names should be concatenated with - instead of _, e.g. file-name.js rather than file_name.js, because in atom/atom module names are usually in the module-name form. This rule only applies to .js files.

  • 在适当的情况下使用较新的 ES6/ES2015 语法

    ¥Use newer ES6/ES2015 syntax where appropriate

    • const 表示要求和其他常量。如果该值是原始值，请使用大写命名（例如 const NUMBER_OF_RETRIES = 5）。

      ¥const for requires and other constants. If the value is a primitive, use uppercase naming (eg const NUMBER_OF_RETRIES = 5).

    • let 用于定义变量

      ¥let for defining variables

    • 箭头函数 代替 function () { }

      ¥Arrow functions instead of function () { }

    • 模板字面量 而不是使用 + 进行字符串连接

      ¥Template literals instead of string concatenation using +

命名事物​

¥Naming Things

Electron API 使用与 Node.js 相同的大小写方案：

¥Electron APIs uses the same capitalization scheme as Node.js:

  • 当模块本身是 BrowserWindow 这样的类时，使用 PascalCase。

    ¥When the module itself is a class like BrowserWindow, use PascalCase.

  • 当模块是一组 API 时，例如 globalShortcut，请使用 camelCase。

    ¥When the module is a set of APIs, like globalShortcut, use camelCase.

  • 当 API 是对象的属性，并且它足够复杂，需要单独放在一个章节中（例如 win.webContents）时，请使用 mixedCase。

    ¥When the API is a property of object, and it is complex enough to be in a separate chapter like win.webContents, use mixedCase.

  • 对于其他非模块 API，请使用自然标题，例如 <webview> Tag 或 Process Object。

    ¥For other non-module APIs, use natural titles, like <webview> Tag or Process Object.

创建新的 API 时，最好使用 getter 和 setter，而不是 jQuery 的单函数风格。例如，.getText() 和 .setText(text) 优于 .text([text])。上面有一个 discussion。

¥When creating a new API, it is preferred to use getters and setters instead of jQuery's one-function style. For example, .getText() and .setText(text) are preferred to .text([text]). There is a discussion on this.