The Shapes of Code

Re:The Shapes of Code by nerdponx on Tuesday January 28, 2020 @08:15AM (#22169019)

    def clean_start_year(x):
        # Account for the 7 year offset in the database
        return x + 7

    def process_record(record):
        record['start year'] = clean_start_year(record['record'])

It's perfectly obvious what this code does, but without the comment it's totally unclear why it does what it does.

[ Parent | on HN ]

Re:The Shapes of Code by clarry on Tuesday January 28, 2020 @09:33AM (#22169666)

   const database_year_offset = 7;

   fix_start_year(year):
       return year + database_year_offset;

   process_record(record):
       record['start year'] = fix_start_year(record['record']);

In this version with one less magic constant (and renamed function), the comment would look very redundant.

DougBTX had the same idea, at the same time. I don't think their version needs the comment either. EDIT: Dang you removed a perfectly fine post :)

[ Parent | on HN ]

Re:The Shapes of Code by nerdponx on Tuesday January 28, 2020 @09:50AM (#22169838)

I guess, but I think it's more that my example fails to illustrate the point well.

Informative comments cannot always be "factored out" like this. Do you at least agree that a ticket or bug #, or a link to an issue in an issue tracker, would be appropriate?

[ Parent | on HN ]

Re:The Shapes of Code by clarry on Tuesday January 28, 2020 @10:08AM (#22170041)

I think a comment is appropriate if the problem cannot be factored out. But in my experience such things can be factored out most of the time, hence the argument that most code should be boring and immediately obvious.

[ Parent | on HN ]

Re:The Shapes of Code by Firadeoclus on Tuesday January 28, 2020 @10:37AM (#22170320)

Factoring out a comment into code sometimes loses information. I would argue that database_year_offset is not as informative as the original comment. Free form text can say things better than identifier names.

[ Parent | on HN ]

Re:The Shapes of Code by nerdponx on Tuesday January 28, 2020 @07:21PM (#22175751)

Most code, sure. But it's not an ideal to be striven for, or a metric to be used when evaluating code.

[ Parent | on HN ]

Re:The Shapes of Code by taneq on Tuesday January 28, 2020 @08:33AM (#22169169)

Ah, the inline equivalent of Doxygen-for-the-sake-of-Doxygen documentation.

    int frob(const int x, void *context)
    Performs a frob on x in the given context.
    Parameters:
      x - int param
      context - a pointer to context
    Returns an id of the frob performed.

[ Parent | on HN ]

Re:The Shapes of Code by clarry on Tuesday January 28, 2020 @09:55AM (#22169902)

I see a lot of this at work, sigh.

The better a variable / function is named (and the better its scope or purpose is limited to one thing), the less it needs comments. So there are a lot of self explanatory variables or functions with doxygen comments that state exactly the same thing the name already does, without adding anything besides noise. And then there are some poorly named things where the exact same thing happens: comment re-states what the bad identifier states. Sigh. Genuinely useful comments are rather rare.

[ Parent | on HN ]

Re:The Shapes of Code by nerdponx on Tuesday January 28, 2020 @12:51PM (#22171932)

How is what I posted an example of this, in any way?

Use your imagination. The "cleaning" routine might not be a one-liner. Maybe it depends on multiple functions from another file/package/library.

[ Parent | on HN ]

Re:The Shapes of Code by AnanasAttack on Wednesday January 29, 2020 @12:41AM (#22177802)

The comment doesn't explain why there even is an offset in the first place. Who put it there and why? I think this should be explained as well

[ Parent | on HN ]