Deno 风格指南

注意

请注意，这是 Deno 运行时和 Deno 标准库中**内部运行时代码**的风格指南。这并非 Deno 用户的通用风格指南。

版权声明 Jump to heading

// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.

文件名中使用下划线而非破折号 Jump to heading

示例：使用 file_server.ts 而非 file-server.ts。

为新功能添加测试 Jump to heading

每个模块都应包含或附带对其公共功能的测试。

TODO 注释 Jump to heading

TODO 注释通常应在括号中包含一个 issue 号或作者的 GitHub 用户名。示例

// TODO(ry): Add tests.
// TODO(#123): Support Windows.
// FIXME(#349): Sometimes panics.

不鼓励元编程，包括使用 Proxy Jump to heading

明确表达，即使这意味着更多的代码。

在某些情况下，使用此类技术可能是有意义的，但在绝大多数情况下并非如此。

包容性代码 Jump to heading

请遵循 https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/inclusive_code.md 中概述的包容性代码指南。

Rust Jump to heading

遵循 Rust 约定并与现有代码保持一致。

TypeScript Jump to heading

代码库的 TypeScript 部分是标准库 std。

使用 TypeScript 而非 JavaScript Jump to heading

不要使用 `index.ts`/`index.js` 作为文件名 Jump to heading

Deno 不会对 "index.js" 或 "index.ts" 进行特殊处理。使用这些文件名会让人误以为它们可以从模块说明符中省略，但实际上不能。这会造成混淆。

如果代码目录需要一个默认入口点，请使用文件名 mod.ts。文件名 mod.ts 遵循 Rust 的约定，比 index.ts 短，并且没有关于其工作方式的任何先入为主的观念。

导出的函数：最多 2 个参数，其余放入 options 对象 Jump to heading

设计函数接口时，请遵循以下规则。

作为公共 API 一部分的函数接受 0-2 个必需参数，外加（如果需要）一个 options 对象（因此总共最多 3 个）。
可选参数通常应放入 options 对象中。

如果只有一个可选参数且似乎将来不可能添加更多可选参数，那么不在 options 对象中的可选参数可能是可接受的。
'options' 参数是唯一一个常规 'Object' 参数。

其他参数可以是对象，但它们必须通过以下方式在运行时与“普通”对象区分开来：
- 一个独特的原型（例如 Array, Map, Date, class MyThing）。
- 一个众所周知的 Symbol 属性（例如带有 Symbol.iterator 的可迭代对象）。
这使得 API 能够以向后兼容的方式演进，即使 options 对象的位置发生变化。

// BAD: optional parameters not part of options object. (#2)
export function resolve(
  hostname: string,
  family?: "ipv4" | "ipv6",
  timeout?: number,
): IPAddress[] {}

// GOOD.
export interface ResolveOptions {
  family?: "ipv4" | "ipv6";
  timeout?: number;
}
export function resolve(
  hostname: string,
  options: ResolveOptions = {},
): IPAddress[] {}

export interface Environment {
  [key: string]: string;
}

// BAD: `env` could be a regular Object and is therefore indistinguishable
// from an options object. (#3)
export function runShellWithEnv(cmdline: string, env: Environment): string {}

// GOOD.
export interface RunShellOptions {
  env: Environment;
}
export function runShellWithEnv(
  cmdline: string,
  options: RunShellOptions,
): string {}

// BAD: more than 3 arguments (#1), multiple optional parameters (#2).
export function renameSync(
  oldname: string,
  newname: string,
  replaceExisting?: boolean,
  followLinks?: boolean,
) {}

// GOOD.
interface RenameOptions {
  replaceExisting?: boolean;
  followLinks?: boolean;
}
export function renameSync(
  oldname: string,
  newname: string,
  options: RenameOptions = {},
) {}

// BAD: too many arguments. (#1)
export function pwrite(
  fd: number,
  buffer: ArrayBuffer,
  offset: number,
  length: number,
  position: number,
) {}

// BETTER.
export interface PWrite {
  fd: number;
  buffer: ArrayBuffer;
  offset: number;
  length: number;
  position: number;
}
export function pwrite(options: PWrite) {}

注意：当其中一个参数是函数时，您可以灵活调整顺序。请参阅 Deno.serve、Deno.test、Deno.addSignalListener 等示例。另请参阅这篇文章。

导出所有用作导出成员参数的接口 Jump to heading

无论何时您使用的接口包含在导出成员的参数或返回类型中，您都应该导出所使用的接口。例如

// my_file.ts
export interface Person {
  name: string;
  age: number;
}

export function createPerson(name: string, age: number): Person {
  return { name, age };
}

// mod.ts
export { createPerson } from "./my_file.ts";
export type { Person } from "./my_file.ts";

最小化依赖；避免循环导入 Jump to heading

尽管 std 没有外部依赖，我们仍需谨慎，以保持内部依赖的简单性和可管理性。特别是要小心不要引入循环导入。

如果文件名以下划线开头：`_foo.ts`，请勿链接到它 Jump to heading

在某些情况下，内部模块可能必不可少，但其 API 不应是稳定的或被链接的。在这种情况下，请在其名称前加上下划线。按照约定，只有其自身目录中的文件才应导入它。

为导出的符号使用 JSDoc Jump to heading

我们致力于完整的文档。理想情况下，每个导出的符号都应该有一行文档说明。

如果可能，JSDoc 使用单行。示例

/** foo does bar. */
export function foo() {
  // ...
}

文档易于人类阅读固然重要，但还需要提供额外的样式信息，以确保生成的文档更具富文本效果。因此，JSDoc 通常应遵循 Markdown 标记来丰富文本。

虽然 Markdown 支持 HTML 标签，但在 JSDoc 块中禁止使用它们。

代码字符串字面量应使用反引号 (`) 而非引号括起来。例如

/** Import something from the `deno` module. */

除非函数参数的意图不明显（但如果意图不明显，则应重新考虑 API 设计），否则不要对其进行文档说明。因此，通常不应使用 @param。如果使用 @param，则不应包含 type，因为 TypeScript 已是强类型。

/**
 * Function with non-obvious param.
 * @param foo Description of non-obvious parameter.
 */

应尽可能减少垂直间距。因此，单行注释应写为

/** This is a good single-line JSDoc. */

而不是

/**
 * This is a bad single-line JSDoc.
 */

代码示例应使用 Markdown 格式，例如

/** A straightforward comment and an example:
 * ```ts
 * import { foo } from "deno";
 * foo("bar");
 * ```
 */

代码示例不应包含额外的注释，且不得缩进。它已经位于注释内部。如果需要进一步的注释，则说明它不是一个好的示例。

使用指令解决代码规范问题 Jump to heading

目前，构建过程使用 dlint 来验证代码中的代码规范问题。如果任务需要不符合 linter 规范的代码，请使用 deno-lint-ignore <code> 指令来抑制警告。

// deno-lint-ignore no-explicit-any
let x: any;

这可以确保持续集成过程不会因代码规范问题而失败，但应谨慎使用此指令。

每个模块都应附带一个测试模块 Jump to heading

每个具有公共功能的模块 foo.ts 都应附带一个测试模块 foo_test.ts。std 模块的测试由于其不同的上下文，应放在 std/tests 中；否则，它应与被测试模块并列。

单元测试应明确 Jump to heading

为了更好地理解测试，函数应根据测试命令中的提示正确命名。例如

foo() returns bar object ... ok

测试示例

import { assertEquals } from "@std/assert";
import { foo } from "./mod.ts";

Deno.test("foo() returns bar object", function () {
  assertEquals(foo(), { bar: "bar" });
});

注意：有关更多信息，请参阅跟踪 issue。

顶层函数不应使用箭头语法 Jump to heading

顶层函数应使用 function 关键字。箭头语法应仅限于闭包。

不推荐

export const foo = (): string => {
  return "bar";
};

推荐

export function foo(): string {
  return "bar";
}

常规函数和箭头函数在提升、绑定、参数和可构造性方面具有不同的行为。function 关键字清晰地表明了定义函数的意图，提高了可读性和调试时的可追踪性。

错误消息 Jump to heading

从 JavaScript / TypeScript 抛出的面向用户的错误消息应清晰、简洁、一致。错误消息应采用句子大小写（首字母大写），但不应以句号结尾。错误消息应避免语法错误和拼写错误，并使用美式英语书写。

注意

请注意，错误消息风格指南仍在完善中，并非所有错误消息都已更新以符合当前风格。

应遵循的错误消息风格

消息应以大写字母开头

Bad: cannot parse input
Good: Cannot parse input

消息不应以句号结尾

Bad: Cannot parse input.
Good: Cannot parse input

消息应为字符串值使用引号

Bad: Cannot parse input hello, world
Good: Cannot parse input "hello, world"

消息应说明导致错误的操作

Bad: Invalid input x
Good: Cannot parse input x

应使用主动语态

Bad: Input x cannot be parsed
Good: Cannot parse input x

消息不应使用缩写形式

Bad: Can't parse input x
Good: Cannot parse input x

提供额外信息时，消息应使用冒号。绝不应使用句号。可根据需要使用其他标点符号

Bad: Cannot parse input x. value is empty
Good: Cannot parse input x: value is empty

附加信息应描述当前状态，如果可能，还应以肯定语气描述所需状态

Bad: Cannot compute the square root for x: value must not be negative
Good: Cannot compute the square root for x: current value is ${x}
Better: Cannot compute the square root for x as x must be >= 0: current value is ${x}

std Jump to heading

不要依赖外部代码。 Jump to heading

https://jsr.deno.org.cn/@std 旨在作为所有 Deno 程序都可以依赖的基础功能。我们希望向用户保证此代码不包含可能未经审查的第三方代码。

记录并维护浏览器兼容性。 Jump to heading

如果模块兼容浏览器，请在模块顶部的 JSDoc 中包含以下内容

// This module is browser-compatible.

通过不使用全局 Deno 命名空间或对其进行功能测试来维护此类模块的浏览器兼容性。确保任何新依赖项也兼容浏览器。

优先使用 # 而非 private 关键字 Jump to heading

在标准模块代码库中，我们优先使用私有字段 (#) 语法而非 TypeScript 的 private 关键字。私有字段即使在运行时也使属性和方法保持私有。另一方面，TypeScript 的 private 关键字仅在编译时保证其私有性，而这些字段在运行时是可公开访问的。

推荐

class MyClass {
  #foo = 1;
  #bar() {}
}

不推荐

class MyClass {
  private foo = 1;
  private bar() {}
}

命名约定 Jump to heading

函数、方法、字段和局部变量使用 camelCase。类、类型、接口和枚举使用 PascalCase。静态顶层项使用 UPPER_SNAKE_CASE，例如 string、number、bigint、boolean、RegExp、静态项数组、静态键值记录等。

推荐

function generateKey() {}

let currentValue = 0;

class KeyObject {}

type SharedKey = {};

enum KeyType {
  PublicKey,
  PrivateKey,
}

const KEY_VERSION = "1.0.0";

const KEY_MAX_LENGTH = 4294967295;

const KEY_PATTERN = /^[0-9a-f]+$/;

不推荐

function generate_key() {}

let current_value = 0;

function GenerateKey() {}

class keyObject {}

type sharedKey = {};

enum keyType {
  publicKey,
  privateKey,
}

const key_version = "1.0.0";

const key_maxLength = 4294967295;

const KeyPattern = /^[0-9a-f]+$/;

当名称采用 camelCase 或 PascalCase 时，即使其中包含缩写，也始终遵循其规则。

注意：Web API 使用大写缩写（JSON、URL、URL.createObjectURL() 等）。Deno 标准库不遵循此约定。

推荐

class HttpObject {
}

不推荐

class HTTPObject {
}

推荐

function convertUrl(url: URL) {
  return url.href;
}

不推荐

function convertURL(url: URL) {
  return url.href;
}

Deno 风格指南

版权声明 Jump to heading#

文件名中使用下划线而非破折号 Jump to heading#

为新功能添加测试 Jump to heading#

TODO 注释 Jump to heading#

不鼓励元编程，包括使用 Proxy Jump to heading#

包容性代码 Jump to heading#

Rust Jump to heading#

TypeScript Jump to heading#

使用 TypeScript 而非 JavaScript Jump to heading#

不要使用 index.ts/index.js 作为文件名 Jump to heading#

导出的函数：最多 2 个参数，其余放入 options 对象 Jump to heading#

导出所有用作导出成员参数的接口 Jump to heading#

最小化依赖；避免循环导入 Jump to heading#

如果文件名以下划线开头：_foo.ts，请勿链接到它 Jump to heading#

为导出的符号使用 JSDoc Jump to heading#

使用指令解决代码规范问题 Jump to heading#

每个模块都应附带一个测试模块 Jump to heading#

单元测试应明确 Jump to heading#

顶层函数不应使用箭头语法 Jump to heading#

错误消息 Jump to heading#

std Jump to heading#

不要依赖外部代码。 Jump to heading#

记录并维护浏览器兼容性。 Jump to heading#

优先使用 # 而非 private 关键字 Jump to heading#

命名约定 Jump to heading#

您找到所需内容了吗？

版权声明 Jump to heading

文件名中使用下划线而非破折号 Jump to heading

为新功能添加测试 Jump to heading

TODO 注释 Jump to heading

不鼓励元编程，包括使用 Proxy Jump to heading

包容性代码 Jump to heading

Rust Jump to heading

TypeScript Jump to heading

使用 TypeScript 而非 JavaScript Jump to heading

不要使用 `index.ts`/`index.js` 作为文件名 Jump to heading

导出的函数：最多 2 个参数，其余放入 options 对象 Jump to heading

导出所有用作导出成员参数的接口 Jump to heading

最小化依赖；避免循环导入 Jump to heading

如果文件名以下划线开头：`_foo.ts`，请勿链接到它 Jump to heading

为导出的符号使用 JSDoc Jump to heading

使用指令解决代码规范问题 Jump to heading

每个模块都应附带一个测试模块 Jump to heading

单元测试应明确 Jump to heading

顶层函数不应使用箭头语法 Jump to heading

错误消息 Jump to heading

std Jump to heading

不要依赖外部代码。 Jump to heading

记录并维护浏览器兼容性。 Jump to heading

优先使用 # 而非 private 关键字 Jump to heading

命名约定 Jump to heading