News for hackers. Stuff that matters.
Re:Perfection is a modern heresy by dsfyu404ed on Monday September 04, 2017 @10:03PM (#15172016)
You are not writing code for just you. There may be times when people fresh out of college who do not speak English as their primary language may need to understand your source.

There is often back-story that needs to be explained. Something as obvious as input sensitization may have a more specific meaning behind the specific implementation, for example a legacy Orcale DB client that chokes on certain special characters. A comment in a case like that can prevent you from getting woken up at 1am because a well meaning attempt to apply the same naming rules to schemas as you do to everything broke things.

If someone says they "don't understand your code" then either they suck at understanding code, you suck at writing it or both.

Comments are a tool to increase the speed and accuracy with which someone else can understand your code.

Re:Perfection is a modern heresy by btschaegg on Tuesday September 05, 2017 @12:31AM (#15172539)
I don't really think this goes against what mikekchar said, though. Take your own example (the legacy oracle client):

The code you're using to escape those specific characters should ideally be written in such a way that its intent is obvious even to a novice reading it. For the novice, then, the question shifts from "WTF does this do?" to "why is this here?", which would be a great example what to actually write comments for: context.

Imagine you're writing some very math-heavy library. Ideally, I shouldn't be a language expert to be able to see what your code does. This still doesn't help me if I don't understand the underlying math, however. Even hints like "this operation is called XY and can be used to Z" may be very helpful if someone wants to get a hold of what it does. With that, you can look up literature for this specific part.

Re:Perfection is a modern heresy by mikekchar on Tuesday September 05, 2017 @01:58AM (#15172831)
Yep. I don't disagree with either of you. I was really responding to the comment that your comments should form a kind of running commentary of the code (something which I completely bought into when I was younger, but then moved away from). There are certain things you can't express with code. I don't want to suggest that you stubbornly refuse to express it at all in those cases :-). It's just that it's a technique of last resort, not a technique of first resort (if that makes any sense).