Beware the Siren Song of Comments • Hacker News Board

Re: Beware the Siren Song of Comments

#31

Post by [deleted] » Wed, Aug 27, 2014, 10:23 PM UTC

arjie wrote: post #16

bunderbunder wrote: post #9

> The right place to document [performance] hacks is a commit message. This advice strikes me as patently insane. Serious performance hacks often involve subtle interactions among different parts of the code. When that happens, properly documenting them requires explaining what's going on in a line of code, for every line of code, right next to that line of code. Just sticking a wall of text somewhere else entirely a…

Likely to be using a workflow that uses `git blame` or equivalent to understand the context of code. The problem that is intended to fix is that comments don't stay in sync with the code they're commenting about. The problem it introduces is discoverability. You have to search to see where this code came from in order to understand it. That isn't going to happen unless you're disciplined. And we're all undisciplined…

[deleted]

Re: Beware the Siren Song of Comments

#32

Post by collyw » Thu, Aug 28, 2014, 12:39 PM UTC

I can't see why he thinks his second example is any more readable than his first. The commented version explains what will happen. The second version requires at least some knowledge of the context.

There are plenty of times when I have been given bits of other peoples code and told to make them work. All I have is an error message. Usually very little context about what the program is doing or why. In these cases, comments make a world of difference.

Even in my own code, looking back on it after 6 months. Sure, I can read the code and understand it, but it will take me 5 times longer than if there is a helpful comment near each step.

Re: Beware the Siren Song of Comments

#33

Post by collyw » Thu, Aug 28, 2014, 12:48 PM UTC

RyanMcGreal wrote: post #4

With respect to TODOs and FIXMEs in the comments, I use them to mark places I know I will need to go back. Before calling a piece of code done, I grep for TODO and FIXME to make sure I haven't left anything unfinished.

Eclipse / Pydev even pulls these out and lists them in a "tasks" panel for you.

Re: Beware the Siren Song of Comments

#34

Post by Nerdfest » Sat, Aug 30, 2014, 5:41 AM UTC

wehadfun wrote: post #14

1st Point: use self documenting code instead of commenting | Ok fine 2nd Point: Explain performance hacks in commit description | might was well not explain them at all. This is a great place to hide the reason for the performance hack 3rd point: Don't use TODO / FIXME | I'm on the fence. 4th Point: Don't comment out old code use version control for old stuff | Ok

TODOs are presented in task lists, etc, by many IDEs. For me, they're included in my workflow, not forgotten.