Question

我发现自己编写了一些棘手的算法代码，我试图对它进行评论，因为我真的不知道谁将维护这部分代码。
遵循这个想法，我写了很多块和内联的评论，也试图不要过度评论它。但是，当我回到我一周前写的代码时，我发现很难阅读，因为评论的存在，特别是内联的。我认为缩进它们（至〜120char）可以轻松实现可读性，但显然根据样式标准会使得线路太长。

以下是原始代码的示例：

fooDataTableOccurrence = nestedData.find("table=\"public\".")
if 0 > fooDataTableOccurrence:  # selects only tables without tag value "public-"
    otherDataTableOccurrence = nestedData.find("table=")
    dbNamePos = nestedData.find("dbname=") + 7   # 7 is the length of "dbname="
    if -1 < otherDataTableOccurrence:  # selects only tables with tag value "table="
        # database resource case
        resourceName = self.findDB(nestedData, dbNamePos, otherDataTableOccurrence, destinationPartitionName)
        if resourceName:  #if the resource is in a wrong path
            if resourceName in ["foo", "bar", "thing", "stuff"]:
                return True, False, False  # respectively isProjectAlreadyExported, isThereUnexpectedData and wrongPathResources
            wrongPathResources.append("Database table: " + resourceName)

以下是内联评论的缩进方式：

fooDataTableOccurrence = nestedData.find("table=\"public\".")
if 0 > seacomDataTableOccurrence:                                                                       # selects only tables without tag value "public-"
    otherDataTableOccurrence = nestedData.find("table=")
    dbNamePos = nestedData.find("dbname=") + 7                                                          # 7 is the length of "dbname="
    if -1 < otherDataTableOccurrence:                                                                   #selects only tables with tag value "table=" 
        # database resource case
        resourceName = self.findDB(nestedData, dbNamePos, otherDataTableOccurrence, destinationPartitionName)
        if resourceName:                                                                                # if the resource is in a wrong path
            if resourceName in ["foo", "bar", "thing", "stuff"]:
                return True, False, False                                                               # respectively isProjectAlreadyExported, isThereUnexpectedData and wrongPathResources
            wrongPathResources.append("Database table: " + resourceName)

代码是用Python编写的（我的公司遗留代码并没有严格遵循PEP8标准，因此我们必须坚持使用），但我的观点不是关于代码本身的清晰度，而是关于注释< / strong>即可。我正在寻找可读性和易于理解代码之间的权衡，有时我发现难以同时实现两者 哪个例子更好？如果没有，会是什么？

Answer 1

也许这是一个XY_Problem？
评论可以完全取消吗？

这是一个（快速和肮脏）尝试重构发布的代码：

dataTableOccurrence_has_tag_public = nestedData.find("table=\"public\".") > 0

if dataTableOccurrence_has_tag_public:
    datataTableOccurrence_has_tag_table = nestedData.find("table=") > 0

    prefix = "dbname="
    dbNamePos = nestedData.find(prefix) + len(prefix)

    if datataTableOccurrence_has_tag_table:
        # database resource case
        resourceName = self.findDB(nestedData, 
                                   dbNamePos, 
                                   otherDataTableOccurrence, 
                                   destinationPartitionName)

        resource_name_in_wrong_path = len(resourceName) > 0

        if resourceNameInWrongPath:

            if resourceName in ["foo", "bar", "thing", "stuff"]:
                project_already_exported = True
                unexpected_data = False
                return project_already_exported, 
                       unexpected_data, 
                       resource_name_in_wrong_path

            wrongPathResources.append("Database table: " + resourceName)

进一步的工作可能涉及从代码块中提取函数。

缩进内联评论是一种好习惯吗？

1 个答案: