简体   繁体   中英

Is it good practise to indent inline comments?

I found myself writing some tricky algorithmic code, and I tried to comment it as well as I could since I really do not know who is going to maintain this part of the code.
Following this idea, I've wrote quite a lot of block and inline comments, also trying not to over-comment it. But still, when I go back to the code I wrote a week ago, I find it difficult to read because of the swarming presence of the comments, especially the inline ones. I though that indenting them (to ~120char) could easy the readability, but would obviously make the line way too long according to style standards.

Here's an example of the original code:

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)

And here's how indenting inline comments would look like:

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)

The code is in Python (my company legacy code is not drastically following the PEP8 standard so we had to stick with that), but my point is not about the cleanness of the code itself, but on the comments . I am looking for a trade-off between readability and easy understanding of the code, and sometimes I find difficult achieving both at the same time

Which of the examples is better? If none, what would be?

Maybe this is an XY_Problem?
Could the comments be eliminated altogether?

Here is a (quick & dirty) attempt at refactoring the code posted:

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)

Further work could involve extracting functions out of the block of code.

The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.

 
粤ICP备18138465号  © 2020-2024 STACKOOM.COM