用途:通过文档和注释传达代码的预期行为与上下文,促进团队知识共享。适用于需要降低理解成本、方便新人上手和维护者接手的代码库。
主要能力:编写说明非显而易见代码的内联注释,例如解释复杂算法、变通做法或重要决策;撰写模块与系统层面的高层文档,如项目 README,说明搭建方式和整体架构;对废弃内容加以标注并说明原因;遵循项目的文档规范,维护 API 文档、开发者指南、维护者列表等文件。
使用方式:在代码不够自解释处添加解释性注释;将文档视为代码的一部分,行为变化时同步更新相关注释与文档;按项目文档标准维护 README、API 文档、OWNERS 等文件,在参与开源项目时确保其反映当前维护者。
适用场景:团队协作、开源贡献、项目交接与长期维护。
限制:官方资料仅给出原则与示例,未提供具体工具、平台、安装命令或收费信息;实际写法需以所在项目的文档规范为准。