生成注释以解释C++程序的结构

Generate comments to explain the structure of a C++ program

本文关键字：程序 结构 C++ 解释 注释      更新时间：2023-10-16

是否有任何（合理）直接的方法来生成注释来解释C++程序的结构？例如，我想将此代码作为输入：

int main(){
cout << "Hello World!";
return 0;
}

并生成此输出：

int main(){
//create a function called main that returns an integer and takes no parameters.
cout << "Hello World!";
//print the string "Hello World" to the standard output.
return 0;
//the function main returns 0
}

如果可以做到这一点，它可能会使（任何C++程序的语法）对初学者来说稍微不那么令人生畏。

如果无法为C++（使用现有工具）执行此操作，那么（任何类似的工具）是否可用于其他编程语言？

有cdecl工具（和在线版本在 http://cdecl.org/）来解释声明。看一看。

您的示例非常冗长，只会使任何源代码完全不可读。有一些解决方案不那么冗长，但更相关，就像我听说 www.doxygen.org/很受欢迎。

如果我很好地理解您的问题，您会想要一个通过在每行中注入适当的文档来"解释"代码的工具。

据我而言，有趣的是，正如您为初学者所说的那样，并且在现有代码上运行它，以这种方式编写代码是完全没有用的（这就是您获得反对票的原因）。

这些注释只是现有代码的重复，因此完全没有用。如果你改变代码，而不改变注释会发生什么？最糟糕的是，如果您再次运行您的工具，您是否希望它删除旧评论或同时保留它们？

好的注释应该为代码添加有用的信息（作为编码人员的意图，或避免的技巧等），但大声阅读代码只是噪音。

所以要回答你的问题，我认为不，没有工具可以做到这一点。但是，一些IDE可能会提供类似的功能，您可以在将鼠标悬停在一行代码上时在工具提示上提供此类信息，但绝对不是代码中的注释。

也许您正在寻找的是有文化的编程？ http://www-cs-faculty.stanford.edu/~uno/cweb.html

注释不应描述代码将执行的操作。评论应该解释，

  • 意图是什么，必须执行哪些任务
  • 程序员期望什么，为什么要采用特定的分支
  • 为什么程序员以这种方式编写代码
在我看来

，目的并不是在程序中实际包含此类评论。初学者只能有某种方式问"这种语法是什么意思？对于特定的事情，有一些有限的解决方案，例如声明语法的 cdecl.org，但没有通用的。这可不是微不足道的。也许可以在 Clang 库之上相对容易地（只是相对地）构建一些东西来处理 c++。

你在注释中输入的内容没有多大意义 - 函数返回整数或不带参数的事实对于函数原型来说是不言自明的。但是，如果您指的是解释函数如何工作的自动注释工具，那么有一些东西。

我不确定这是否适用于C++，就像它适用于 C# 一样，但是有一个名为 GhostDoc 的 Visual Studio 插件，它根据变量/函数/等名称等生成"人类语言"注释。你可以在这里看到它的实际效果：http://www.youtube.com/watch?v=4aA4VZoVDQw（视频的第二部分）。

即使它不能完全解决您的问题，也许它会给您一个提示，告诉您要寻找什么。

相关文章：