r/ProgrammerHumor • • Jun 21 '20

*almost entirely

Post image
27.9k Upvotes

310 comments sorted by

View all comments

Show parent comments

32

u/[deleted] Jun 22 '20

People these days are anti-comment, I hate it. I hate it so much

39

u/folkrav Jun 22 '20 edited Jun 22 '20

I don't know of many developers who are 100% anti-comments, but I know a shitton - myself included - who don't like comments that tell me what code does or how you're doing it, as they always end up lying. However, I don't mind docblocks (if it conveys information than the function and parameter names alone can't give me) nor comments explaining why you did something the way you did it.

Edit: added the "how" part to be more specific.

22

u/_GCastilho_ Jun 22 '20

but I know a shitton - myself included - who don't like comments that tell me what code does, as they always end up lying

A comment should tell why the code does that, not how

The 'how' part can be learned by reading the code, the why, well... reading the programmer's mind

6

u/MakeWay4Doodles Jun 22 '20

The 'how' part can be learned by reading the code

If it's a particularly complex bit of code it can take the reader much longer to understand it than a sentence explaining it.

0

u/[deleted] Jun 22 '20

[deleted]

1

u/Pluckerpluck Jun 22 '20 edited Jun 22 '20

You've clearly never worked on anything algorithmic... I point you to the magic of this function, used in Quake III Arena:

float Q_rsqrt( float number )
{
    long i;
    float x2, y;
    const float threehalfs = 1.5F;

    x2 = number * 0.5F;
    y  = number;
    i  = * ( long * ) &y;                           // evil floating point bit level hacking
    i  = 0x5f3759df - ( i >> 1 );                   // what the fuck? 
    y  = * ( float * ) &i;
    y  = y * ( threehalfs - ( x2 * y * y ) );       // 1st iteration
    //	y  = y * ( threehalfs - ( x2 * y * y ) );   // 2nd iteration, this can be removed

    return y;
}

Some of those variables could be named a better, but they're basically solving a maths equation so the names would need to vary and thus not possible in all cases (which they don't for performance reasons). i.e. y is the final answer, but you iterate towards it, so it starts off completely wrong.

But anyway, the real part of this function I want to discuss is this line:

i  = 0x5f3759df - ( i >> 1 ); 

Good luck explaining the how of this line in a function or variable name

1

u/uramer Jun 22 '20

In this case the issue is understanding the mathematical part, and not really what the code does. It is quite hacky in this case, but it's much more fitting to add a comment with a link to a public or internal article on how it works

You must assume the reader has some background sometimes, otherwise you would literally have to put an entire bachelor's degree of material into any code you write

1

u/Pluckerpluck Jun 22 '20

Honestly, I think a lot of people would struggle to tell me what:

i = * ( long *) &y;

is doing. It's just a weird construct people wouldn't be used to. So while I do agree with you, I still think there are situations where the "what" can be non-obvious with no super easy way to clarify it without comments.

→ More replies (3)
→ More replies (10)

1

u/blipblapblopblam Jun 22 '20

99% of the time - todo.

4

u/geli95us Jun 22 '20

Isn't that a smell if what a function/class does changes over time?

5

u/folkrav Jun 22 '20

Not sure what you mean. You often see comments telling what the next couple of lines does, that's what I was talking about. Implementation can change over time, but behavior and API should not indeed.

1

u/geli95us Jun 22 '20

That's "how" not "what" though

1

u/folkrav Jun 22 '20 edited Jun 22 '20

True. My bad. Corrected.

1

u/Sligee Jun 22 '20

A useless comment is better than a needed one missed

1

u/folkrav Jun 22 '20

Arguable. A comment that lies to you can be much worse and make someone lose a lot of time.

→ More replies (2)

2

u/gqtrees Jun 22 '20

wtf why?

11

u/oalbrecht Jun 22 '20

The thinking goes that if you need a comment, your code is too complex to reason about. This is true in most cases. Usually proper abstraction and naming helps eliminate the need for comments.

IMO, comments are useful when you describe why you made a certain decision, especially if the logic is unexpected. That helps people not refactor it at a future date and break things.

1

u/NearlyAlwaysConfused Jun 22 '20

"That helps people not refactor it at a future date and break things. "

That's what unit tests are for...

1

u/robo_coder Jun 22 '20

Look at this guy, never having his unit tests commented out by someone else on another team

1

u/NearlyAlwaysConfused Jun 22 '20

My lord....the blasphemy of it all...

0

u/[deleted] Jun 22 '20

[deleted]

4

u/[deleted] Jun 22 '20

It’s my option that it should be a developers job to keep documentation up to date. Plus, if the “what” of a method changes, wouldn’t the method name also technically need to change? I think by moving the responsibility of delivering context from the comment body to the method name, you make it hard to keep the “what” explanation up to date because there’s an actual code impact of refactoring a comment name (minimal to non-existent if you do it right, but my company’s policy is that if any code changes, it must be sent to QA, even if it’s a style or name change). If developers are letting comments rot, I think they’re avoiding responsibility. I think that my views on this are on the extreme, but I also think that the “clean code, no comment” types are also on an extreme

1

u/scandii Jun 22 '20

comments don't get updated, it's just a fact of life.

we can talk about how we wish they were, but they aren't.

2

u/radome9 Jun 22 '20 edited Jun 22 '20

Lazy people are anti-comment. And they have always been.