使用严格类型输入时docblock类型提示是否多余

我有一个相当大的私有代码库，它已经发展了大约十年。我没有使用phpDocumentor，但是由于使用docblock节已经成为开源项目中的标准，所以我也为存储库中的所有公共方法采用了编写docblock的方法。大多数块仅包含一个小的描述以及所有参数和返回类型的类型提示。

随着静态分析的到来，这些类型提示已帮助我找到了很多不一致之处和可能的错误。最近，我已经使用PHP的typehints将整个代码库（现在在PHP7.2上运行）转换为具有所有参数和返回值的类型提示。现在我在想...这些docblock typehints是否多余？它需要进行大量工作，以使所有docblock与不断变化的代码保持同步，并且由于它们不添加任何新信息，我想知道完全删除它们是否更好。

一方面，即使有多余的内容，删除文档也感觉很糟糕。在另一种情况下，我真的很想打破已经重复进行提示的“不要重复自己做”的日常类型提示内容。

在代码中可以找到的信息不应在注释中重复。

充其量，要使它们保持同步是浪费了精力。他们更有可能最终不同步。那时，他们只是感到困惑。

如果以静态类型的语言（例如Java，C＃）查看DocBlock等效项，则会发现doc注释不包含类型信息。就您的PHP代码而言，我强烈建议您照做。当然，在无法应用类型提示的地方，注释仍然是您的最佳选择。

这与PHP无关，但是当隐式推断类型（例如Haskell）时，重复的类型信息就有意义。

是的，docblock在php 7中变得多余了。

编码中的大部分时间都花在阅读上，因此必须两次阅读同一本书会影响您的工作效率。此外，它很容易错过实际上重要的评论。

我不再写docblock了，除非当我想输入提示某种类型的数组（例如@return int[]或@param SomeStatus[] $statusList）时，或者当我想对方法，参数或返回值添加注释时。我发现禁用在没有alle参数时触发的phpstorm检查非常重要，并且如果您有docblock，则在docblock中返回类型时很重要。

代码和文档通常具有不同的受众：文档是针对该功能的用户的。他们不必看代码就能理解类型。因此，文档应包括所有必要的信息，包括类型。

在某些系统中，不必在文档中指定参数类型，因为该类型可以从代码中获取。PHPDoc不是这样的系统。相反，该@param标签被记录为

提供时，必须包含一个类型以指示期望的内容

减少了“使所有文档块与不断变化的代码保持同步的大量工作”，因为PHPDoc将对照代码类型提示检查文档类型提示。这是一种分析/静态分析，因此使您的文档生成成为自动化测试管道的一部分。

您可能要问自己的另一个问题是，为什么这些功能在“不断变化”中如此详细地记载在文档中。通常的动机是创建界面的HTML参考手册。但是，如果从未在IDE外部阅读过文档，或者如果您没有使文档有意义的稳定接口，则不需要详细的文档块，甚至会产生误导。最好只编写一个摘要，然后将完整的文档推迟到稳定的设计为止。