0

我的项目使用 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 留给那些，但我想知道我是否应该更新任何东西。

  1. 是否有最佳实践或至少普遍接受的方式来处理这种情况（一个与父存储库保持同步的分叉项目），以便我的代码对其他程序员更有用？
  2. 似乎还有很多其他 docblock 参数和选项，例如每个函数的 docblocks。我应该争取推荐的详细程度吗？
  3. 是否有在我的项目中在其他类型的文件（SCSS、JS 等）上添加类似文档的最佳实践？父项目似乎没有，但我有兴趣添加一些。

我的目标是以同事或未来的维护者将来可能会发现有用的格式创建代码和代码内文档。

4

0 回答 0