The Shapes of Code

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 ]