php - 在分叉项目中使用 @package 和 @since 的最佳实践
问题描述
我的项目使用 WordPress 入门主题 FoundationPress。upstream remote
我使用 Github 并在社区改进代码时从父存储库更新我的项目。作为记录,我已经编程了很长时间,但几乎总是一个人,而且我对 docblocks 和代码内文档非常缺乏经验。我知道在某种程度上这可能是基于意见的,因为这似乎是寻找其他答案的趋势,但我觉得我没有掌握正确的用法。
父项目在 PHP 文件上使用如下所示的 PHP Docblocks,每个文件始终只有一次,例如:
/**
* Brief File Description
*
* @package FoundationPress
* @since FoundationPress 1.0.0
*/
当我添加自己的新 PHP 文件时,我一直在添加一个类似的块,但使用我的项目的名称代替:
/**
* Brief File Description
*
* @package MyProject
* @since MyProject 0.1.0
*/
有时,我会使用自己的函数更新现有文件。我一直把@since
这些功能放在上面,所以它是这样的:
/**
* Brief File Description
*
* @package FoundationPress
* @since FoundationPress 1.0.0
*/
function foo() { ... }
function bar() { ... }
/**
* My Function Description
*
* @since MyProject 0.1.0
*/
function my_foo() { ... }
其他时候,我更新了一个现有的函数——我只是把 docblock 留给那些,但我想知道我是否应该更新任何东西。
- 是否有最佳实践或至少普遍接受的方式来处理这种情况(一个与父存储库保持同步的分叉项目),以便我的代码对其他程序员更有用?
- 似乎还有很多其他 docblock 参数和选项,例如每个函数的 docblocks。我应该争取推荐的详细程度吗?
- 是否有在我的项目中在其他类型的文件(SCSS、JS 等)上添加类似文档的最佳实践?父项目似乎没有,但我有兴趣添加一些。
我的目标是以同事或未来的维护者将来可能会发现有用的格式创建代码和代码内文档。
解决方案
推荐阅读
- hyperledger-fabric - Hyperledger Composer 是否必须设置多节点多组织 Hyperledger 结构网络?
- dart - 在初始化程序中只能访问静态成员。Dart2.0
- c# - 在动态表中添加点击事件
- java - 尝试从 Jenkins 发送电子邮件报告时遇到异常
- python - 在 Python 中将 2 列的数据框转换为一系列 2 列
- c# - ASP.NET CORE 中的自定义身份验证和更新声明
- xquery - 查找具有正确“dateTime”格式元素的文档
- javascript - 使用自定义科尔多瓦方案获得安全来源
- elasticsearch - 如何在聚合上应用分组/折叠结果?
- spring - lombok @Builder 类型转换错误