跳转到主要内容

拼写、标点和格式

避免缩略形式​

为了保持我们对话式的风格，一些缩略形式是可以接受的。

  • 包含“is”或“are”的缩略形式。 例如：it's 和 you're。
  • 但是，请谨慎使用缩略形式。

但是，请避免其他缩略形式。 例如：

  • It'll (使用 “It will”)

文本强调​

请谨慎使用文本强调（粗体 和 斜体）。 为了保持文档的平和语气，并提高可读性，请避免大量使用强调和格式化文本。

斜体和粗体文本是强调句子某些部分的绝佳方式，以引起读者的注意。 请更谨慎地使用粗体文本，仅在您希望某些文本在整个段落中脱颖而出时使用（以便读者在仅“扫描”页面而不是正确阅读时可见）。首次引入新概念的词语使用斜体。

请勿使用全部大写来强调文本。

如果您不确定是否要强调某些文本，请不要这样做。

UI 元素​

对于 GUI 元素（按钮、下拉菜单等）的名称，请使用 粗体。同时使用与 GUI 中相同的大小写。 例如：

  1. 在 **File** 菜单中，选择 **Open...**。

避免感叹号​

为了保持我们平和的语气，请勿使用感叹号（感叹号）。

例外：它们在祝贺或欢迎消息中是可以接受的，例如：“恭喜 - 你已完成本教程！”

大写并拼写出专有名词​

虽然你可能想使用诸如 "Postgres" (而不是官方专有名词 "PostgreSQL") 之类的缩写，或者在书写 "Javascript"（而不是 "JavaScript"）时不注意大小写，但我们使用专有名词的官方形式。 一些常见的例子是：

  • Node.js（而不是 Node 或 Node.JS）
  • JavaScript 和 TypeScript（而不是 JavaScript 和 Typescript 或 JS 和 TS）
  • PostgreSQL（而不是 Postgres 或 Postgresql）
  • MongoDB（而不是 Mongo）
  • GitHub（而不是 Github）
  • 对于 JSON，请参阅 特殊情况：JSON

如果您不确定专有名词的拼写，请查看其官方网站。

标题和标头​

  • 标题和标头使用句子大小写：只有首字母大写（例外：大写专有名词）
  • 避免动名词（“配置数据库”，而不是“正在配置数据库”）
  • 除非需要问号，否则请勿在标题或标头的末尾使用标点符号
  • 在标题中使用 code 表示代码 - 这是我们的导航元素所必需的

表格、项目符号列表和编号列表​

表格和列表通常是呈现信息的最简洁方式。 请在感觉合适时使用这些元素。 以下是一些指南：

  • 当列表的顺序无关紧要时，请使用项目符号列表（例如，数据库功能的枚举，这些功能没有固有的顺序）。
  • 仅当列表的顺序重要时才使用编号列表（例如，在提供逐步说明时，其中一个步骤建立在前一个步骤的基础上）。
  • 使用表格来描述共享许多相似属性/特征的事物（例如，API 调用的参数，它们都具有“名称”、“类型”、是必需的还是可选的，并且需要描述）。
  • 对于编号/有序列表和项目符号列表，如果它是一个完整的句子，请在末尾添加句点。 这在有序列表中最常见，其中包含一系列步骤。

连字符​

根据这些规则使用连字符。

有时，有些术语不清楚是否应使用连字符。 为了力求一致，我们在此处列出这些术语。

不使用连字符拼写​

  • 用例
  • 命令行（当将其称为名词时：“在命令行上”。当它是形容词时，请使用连字符：“此命令行选项...”）
  • 自动格式
  • 类型安全（有关“类型安全”的指南，请参见下文）
  • 文件名
  • 编译时（当您将其用作名词时：“...在编译时”。当它是形容词时，请使用连字符：“此编译时操作...”）

拼写为一个单词​

  • 自动完成
  • 代码库

类型安全、类型安全和类型安全性​

  • “代码是类型安全的。”（名词后的形容词）
  • “这是类型安全的代码。”（名词前的形容词）
  • “Prisma ORM 的一个关键特性是类型安全性。”（名词）

数据源和 datasource​

  • datasource 代码块
  • “引入新的数据源时，必须重新生成 Prisma Client”

文件和文件类型​

当您引用文件或文件类型时，请使用小写和代码格式，并包括点。 如果文件名扩展名在发音时以元音开头，请使用“an”作为介词，否则使用“a”

  • 一个 .jpg 文件
  • 一个 .xls 文件
  • 一个 .env 文件
  • 对于 json 文件，请参阅 特殊情况：JSON

注意：当您引用特定文件时，请使用文件名中使用的大小写

  • schema.prisma 文件

特殊情况：JSON​

  • 当您笼统地引用 JSON 时，请使用全部大写且不使用代码格式
  • 当您引用 Prisma Json API 时，请使用 Json
  • 当您引用 JSON 文件时，请使用上述格式化规则：“一个 .json 文件”

对路径和文件名使用内联代码格式​

例如：

  • “默认情况下，生成的 Prisma Client 位于 ./node_modules/.prisma 文件夹中。”
  • “schema.prisma 文件位于...”
  • “要使用多个 .env 文件...”

在文本中引用字符串时，使用内联代码格式​

例如：

“以下查询返回 email 字段等于 Sarah 的所有记录。”

避免过度代码格式化​

如果文档中包含过多特殊格式，则文档会很快在视觉上变得混乱。 我们的文档技术含量很高，我们经常会引用用户代码中出现的代码片段或技术关键字。 对于这些关键字，我们使用代码格式是合适的。 但是，我们不应使用代码格式来引用通用技术（如 JSON）

例如：

Prisma 会自动将 JavaScript 对象（例如 { extendedPetsData: "none"}）转换为 JSON。

使用牛津逗号使列表清晰​

标题除外，请使用牛津逗号。 它是用于三个或多个项目的列表中的倒数第二个项目之后、在“and”或“or”之前的逗号。 这使得事物更清晰。 示例：“...一位意大利画家、雕塑家和建筑师”。

在极少数情况下，牛津逗号会使列表不那么清晰。 在这种情况下，请尽可能重新排列列表，以使含义清晰。

代码片段​

介绍所有代码片段​

编写一个简短的介绍性句子，该句子：

  • 解释代码片段的功能
  • 如果适用，链接到参考文档

例如：

此 createMany() 查询执行以下操作：

  • 创建多个 User 记录
  • 创建多个嵌套的 Post 记录
  • 创建多个嵌套的 Category 记录

尽可能显示查询结果​

使用 <CodeWithResult> 组件来显示查询和该查询的结果。

使用 highlight 注释来突出显示代码​

如果您需要在代码示例中高亮显示行，请使用 highlight 魔术注释。 例如

```prisma
generator client {
  provider        = "prisma-client-js"
  //highlight-next-line
  previewFeatures = ["namedConstraints"]
}
```

格式化代码块和内联代码​

在创建和编辑文档时，请参考以下内容：格式化内联代码和代码块。

强调占位符​

占位符在技术文档中是一个棘手的问题，也是最常见的混淆来源之一，特别是对于初学者。为了力求一致，Prisma 文档中的占位符

  • 全部使用大写字母拼写
  • 以两个下划线为前缀和后缀
  • 使用描述性术语

例如，考虑以下代码块，其中 __DATABASE_CONNECTION_URL__ 是 PostgreSQL 连接 URL 的占位符

datasource db {
  provider = "postgresql"
  url      = "__DATABASE_CONNECTION_STRING__"
}

每当您使用占位符时，请解释如何获取占位符的值，或链接到另一个解释此内容的资源。明确指出这是一个必须替换为“真实值”的占位符。包含一个真实值可能是什么样子的示例

datasource db {
  provider = "postgresql"
  url      = "postgresql://opnmyfngbknppm:XXX@ec2-46-137-91-216.eu-west-1.compute.amazonaws.com:5432/d50rgmkqi2ipus?schema=hello-prisma2"
}

使用具有表达性的变量名​

好的

const getUsers = (...)
const deleteUsers = (...)

不好

const results = (...) // Too generic
const foo = (...) // Too vague

包含有效的代码片段​

确保您包含的代码片段是真实的示例，如果在所呈现的上下文中运行，它们将可以工作。

遵循 Prisma Schema 命名约定​

当您为示例创建 Prisma Schema 时，请遵循我们建议用户使用的命名约定。

在单个代码块中列出 shell 命令​

当您需要提供一系列 CLI 命令作为给读者的说明时，请使用单个代码块。除非您想为每个步骤提供上下文，否则不要使用列表

不好​

  • cd path/to/server
  • docker compose up -d --build
  • ./node_modules/.bin/sequelize db:migrate 或 npx sequelize db:migrate
  • ./node_modules/.bin/sequelize db:seed:all 或 npx sequelize db:seed:all

更好​

cd path/to/server
docker compose up -d --build
./node_modules/.bin/sequelize db:migrate # or `npx sequelize db:migrate`
./node_modules/.bin/sequelize db:seed:all # or `npx sequelize db:seed:all`

或

  1. 导航到项目目录：cd path/to/server
  2. 启动 Docker 容器：docker compose up -d --build
  3. 迁移您的数据库架构：./node_modules/.bin/sequelize db:migrate 或 npx sequelize db:migrate
  4. 为数据库播种：./node_modules/.bin/sequelize db:seed:all 或 npx sequelize db:seed:all

不要在代码块中的 CLI 命令前加上 $​

对 CLI 命令使用 terminal 语言元字符串 - 此类型的代码块包含一个 $

```terminal
npm install prisma
```

例如：

npm install prisma

使用 npm 作为默认的包管理器​

所有示例都应使用 npm。其他包管理器选项（yarn、pnpm、bun）仅在命令不同时才应使用，且永远不应作为默认选项。