python - 记录 doxygen 中的 if 语句

Question

我如何在 doxygen 中记录 if 语句，它记录了我所有的类、函数，但我为 if 语句写的注释，它考虑了下一个最近的变量。

if abc != "":  # Here we check if abc is not equal to null and then check if it is equal to some known values
    if abc != "red":
        if abc != "blue":
            error()

if gfh != ""
    ghf = 0

它正在将注释分配给“ghf = 0”，知道如何将注释分配给 if 语句。

Answer 1

Doxygen 是一种生成 API 文档的工具。也就是说，关于功能和使用的文档将客户端代码的编写者作为目标受众。这些自然不关心实现细节。

您所做的似乎是为您的代码维护者添加文档。那是另一回事，Doxygen 没有解决。

除了一些提高代码可读性的一般经验法则，我不知道是否有工具可以帮助您记录控制流:

• 避免“意大利面条代码”
• 给变量/函数起有意义的名字
• 编写有意义的文档字符串

例如，您可以引入一个函数来执行检查并相应地返回一个 bool 值。这纯粹通过使用标准语言功能来提高可读性。

# you don't even need a comment to find out what the intention is here
if is_invalid(abc):
    error()

另请查看 this post ，也许还有 IPython Notebook可能值得一试。