WordPress 编码标准

内联文档标准

💡 云策文档标注

概述

本文介绍 WordPress 的内联文档标准,说明内联文档对核心开发者、学习 WordPress 的开发者以及 WordPress 开发者代码参考库的重要价值,并列出按语言划分的文档规范与相关资源。

关键要点

  • 内联文档可为未来核心开发提供参考,也帮助其他开发者学习 WordPress,并用于填充 WordPress 开发者代码参考库。
  • 即使开发者熟悉自己的代码,内联文档仍对本人有长期价值,尤其有助于记录复杂函数参数、使用意图,并在日后快速回顾。
  • 应遵循语言特定的文档标准:PHP Documentation Standards 和 JavaScript Documentation Standards。
  • 可参考 “Inline documentation – why you should” 了解编写内联文档的理由与价值。

📄 原文内容

Inline documentation provides a good resource for core developers in future development, and other developers when learning about WordPress. It also provides the information necessary to populate the WordPress developer code reference.

I don’t need to document my code. I wrote all of it – know it like the back of my hand.

“I would argue that, separately, documentation is also for you, the developer. I’ve found quite often that my inline documentation can be a very effective breadcrumb trail when establishing one’s own intent, particularly with regard to complex function arguments and usage. And it’s also helpful to return to a function two years later and find a paragraph in the inline documentation that describes, in meticulous fashion, something that I otherwise would have had to rediscover all over again.” – Nacin

Language-specific Standards

Resources