603
No comment (thelemmy.club)
submitted 3 weeks ago by to c/programminghumor@lemmy.world
50 comments fedilink hide all child comments
 
you are viewing a single comment's thread
view the rest of the comments
[–] 8 points 3 weeks ago* (2 children)

I'd rather the code itself is readable with well-named variables and methods.

There are situations where comments are helpful though

// this foos the bar
foo(bar);

Helps nobody

// this might seem weird, but we had to add this because some customers were complaining about unfood bars and the rest don't seem to mind either way
foo(bar);

Is much more helpful

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 2 child comments
    •
  • [–] 7 points 3 weeks ago

    I’d rather the code itself is readable with well-named variables and methods.

    Unfortunately, sometimes a level of specificity is needed that can't be expressed in a method name alone, unless you make that method name super long. The method name can't always convey:

    • Time and space complexity
    • Side effects
    • Thread safety
    • Possible exceptions
    • Preconditions and postconditions
    • Edge cases

    Sure, some of this can be communicated in the implementation, but that means that users need to control-click the function instead of just hovering to see the comment. And sometimes the implementation is a secret or at least in a different file from the declaration

  • permalink
  • fedilink
  • source
  • parent