README文件：目的、位置和内容

修订历史

1. 版本 1 · 中文README文件：目的、位置和内容

   机器翻译版本。

   2026年11月7日
   查看此版本正文

   README

   自述文件是目录内容的简短摘要。查看包含目录的内容时，文件的内容会显示在GitHub和Gitiles中。README文件为浏览代码的用户（尤其是首次使用的用户）提供关键信息。

   本文档介绍了如何创建可通过markdown读取的README文件。

   可读自述文件

   README文件必须命名 README.md. 文件名 必须 结尾是 .md 扩展名，区分大小写。

   例如，当您查看包含目录的内容时，将呈现文件/README.md ：

   https://github.com/google/styleguide/tree/gh-pages

   也有 README.md 于 HEAD ref由Gitiles在显示仓库索引时渲染：

   https://gerrit.googlesource.com/gitiles/

   将自述文件放在哪里

   与所有其他Markdown文件不同， README.md 文件不应位于您的产品或库的文档目录中。 README.md 文件应位于产品或库的实际代码库的顶级目录中。

   代码包的所有顶级目录都应具有最新的 README.md 文件。这对于为其他团队提供接口的包目录尤其重要。

   在自述文件中应放入哪些内容

   至少，您的 README.md 文件应包含指向用户和/或团队文档的链接。

   每个包级别 README.md 应包括或指向以下信息：

   1. 此包或库中的内容及其用途。
   2. 联络点
   3. 此包或库是否被弃用的状态，是否适用于常规版本等。
   4. 如何使用包或库。示例包括示例代码，可复制 bazel 命令等。
   5. 相关文件的链接。

   ---

   来源与许可

   原文：Google documentation guide

   归属：Google, google/styleguide contributors; documentation from the Google styleguide repository

   许可：CC BY 3.0 Unported

读者评论 0

暂无已公开评论。

登录后可发表评论。