关闭最佳做法文档

close-best-practices 是一个库和一个帮助团队记录其 编码最佳做法.

(有兴趣在这样的项目上工作吗? 关闭 实值 寻找 伟大的工程师 加入我们的队伍!)

哲学

该图书馆的建设体现了以下原则:

1. 文件应尽量贴近编码(最好在 代码)
2. 文档应当可以发现
3. 文档应在相关代码更改时自动更新
4. 你不必仔细看密码才能读到我们最好的 实践

安装

您可以通过 npm 安装此软件包 :

npm i --save-dev @closeio/best-practices-documentation

yarn add -D @closeio/best-practices-documentation

将守则作为最佳做法

您可以用特殊格式的注释标记代码块为最佳做法 :

// @BestPractice React Components
// @BestPractice.subtitle State Updates
// @BestPractice.description
//   If you need to update state based on the current value, use
//   the functional version of the state setter rather than using
//   the `value`. This keeps `useCallback` from creating a new function
//   every time the value changes.
const [value, setValue] = useState(0);
const incrementValue = useCallback(
  () => setValue((currentValue) => currentValue + 1),
  [],
);
// @BestPractice.end

您也可以在 JSX 块中用 {/* ... */} 注释 格式.

检查作为代码一部分的样本项目以看到更多实例.

限制

• 我们目前不支持多行评论.
• 此工具只查看文件 .js, (中文(简体) ), .jsx, (中文(简体) ), .ts,以及 .tsx 扩展

摘录最佳做法文件

为了提取你的最佳做法文档,您可以引用我们的CLI工具:

npx best-practices write -s src/ -g docs/best-practices -u "https://github.com/<your org>/<your repo>/tree/main"

这将扫描您的代码 src 建立最佳做法 从您标记的代码中获取文件。 报告的内容 -g 目录将会是 完全覆盖,所以要确定您指向一个目录,而不是 包含任何手工编写的文档.

这还将写出 digest.txt 用于跟踪更改的文件 您生成的文档 .

检查 Docs 新鲜度

您可以检查您的生成的文档是否已经过时 页:1 check 子命令 :

npx best-practices check -s src/ -g docs/best-practices

这将从您的代码中收集您的最佳做法文档并生成 文摘,并将这些文摘与上次编写的文摘相比较 已生成。 这个 check 命令将以状态代码退出 1 若为 文档已过时, 这使得它成为一个很好的指令 用于前承诺钩或 a CI步骤.

插入块入静态文档

请将一些最佳做法插入(并不断更新)静态 文档,指您自己输入的文档,而不是完全 您可以使用特殊格式的注释和 元标记 .

在您的代码中

在代码中,添加 id 元字段到文档块:

// @BestPractice.id insertIntoStaticDocs

这个ID应该在整个代码库都是独一无二的, 但这个没有检查,或者 由工具执行。 如果您有多个相同标识的最佳做法块 然后工具拾取的最后一个 当解析您的代码时.

在静态文档中

在您的静态标记下文档文件中, 添加这样的评论 喜欢插入最佳做法:

<!-- @BestPractice.insert insertIntoStaticDocs -->
<!-- @BestPractice.end -->

如果你的文件是一个 .mdx 标记下的文件, 使用 JSX 样式注释代替 :

{/* @BestPractice.insert insertIntoStaticDocs */}
{/* @BestPractice.end */}

必须有始发线和终发线,因为它们将作为 边框以知道在哪里替换代码.

从命令行

要写给静态文件, 你必须将工具指向您的文件 根带有 -d 命令行参数.

举个例子.

`npx best-practices write -s src/ -g docs/best-practices -d docs/ ...`

旧身份证

如果将最佳做法插入静态文档,则不会 插入到生成的文档中。 但是,它仍将包括在 检查医生新鲜度的文摘.

不断更新文档

您的文档有几种最新策略:

1. 创建将运行的预承诺钩 best-practices write
2. 创建将运行的预承诺钩 best-practices check
3. 创建将运行的 CI 步骤 best-practices check
4. 如果您拥有自动创建静态的文档系统 文档站点,您可能可以在 best-practices 命令作为其中的一部分.

自定义文档生成

如果默认使用 CLI 工具不符合您的需要, 您可以使用 用于自定义您的最佳做法生成。 我们出口所有的初级 函数 write 财务报告和审定财务报表 check CLI 子命令使用, 您可以 编一些你需要的