News for hackers. Stuff that matters.
Re:Why Not Comments by __MatrixMan__ on Tuesday September 10, 2024 @06:39PM (#41506331)
I like two of the three, but what is the advantage of commenting what the code is doing, when you can use a Trace or Debug message for that instead?
Re:Why Not Comments by PlunderBunny on Tuesday September 10, 2024 @06:51PM (#41506407)
Not the person you are replying to, but I would say that:

- The code 'tells you' what it does

- The comment for the code tells you what the author intended it to do.

The gap between the two is where bugs can be found.

Re:Why Not Comments by readthenotes1 on Tuesday September 10, 2024 @07:00PM (#41506506)
"The comment for the code tells you what the author intended it to do."

Not quite.

The comment for the code tells you what the author of the comment understood the code to do when hen wrote the comment.

Re:Why Not Comments by PlunderBunny on Tuesday September 10, 2024 @07:58PM (#41506871)
It could be that too, but I think that presumes an order - that the comment was written after the code. If the comment was written before the code, then it would describe what the author was trying (intended) to do. Which also implies an order of course.
Re:Why Not Comments by g-b-r on Tuesday September 10, 2024 @08:14PM (#41506979)
Yeah, absolutely check who wrote a comment before relying on it

It's luckily rare for people to add wrong comments, though (and those who do should be publicly fustigated).

By the way, please never state something as it were the truth if you're not sure that it is. Saying "I think" is perfectly fine, and might save people days of investigation.

Re:Why Not Comments by kristiandupont on Wednesday September 11, 2024 @01:53AM (#41508393)
Not the comments I write.

I don't write what the code does or even what "I understand the code to do". I explain choices, especially ones that the next developer or my future self is likely to misunderstand when looking at the code.

Re:Why Not Comments by readthenotes1 on Thursday September 12, 2024 @09:25AM (#41520672)
But what about a year later when someone's changed the code but not the comment?
Re:Why Not Comments by kristiandupont on Thursday September 12, 2024 @12:58PM (#41522963)
I would say that I have observed something like this about as many times as someone has changed some semantics in a way that a variable or function name is no longer correct. That is to say: probably a few times in 25 years, but nothing compared to how much value I have received from them.
Re:Why Not Comments by ykonstant on Wednesday September 11, 2024 @02:52AM (#41508693)
>when hen wrote the comment.

I've always said coding is a cottage industry!

Re:Why Not Comments by CRConrad on Thursday September 12, 2024 @03:10AM (#41518291)
Re:Why Not Comments by __MatrixMan__ on Tuesday September 10, 2024 @09:14PM (#41507275)
I've got no trouble with that perspective, but wouldn't a log message scratch the same itch, plus more?
Re:Why Not Comments by PlunderBunny on Wednesday September 11, 2024 @12:49AM (#41508110)
I've never worked in a company where the commit log message wasn't just a link/reference to something in a bug tracker. I feel like a 'what this block of code does' comment is different from 'what is this change, and why did I make it' commit message.
Re:Why Not Comments by porridgeraisin on Wednesday September 11, 2024 @01:39AM (#41508316)
They meant logging-logs in the code itself:

log.Debugf("Foo is: %#v", ...) //You think: this is probably filtering code log.Debugf("Foo without X is: %#v", ...)

Re:Why Not Comments by edflsafoiewq on Tuesday September 10, 2024 @06:54PM (#41506434)
A function generally tells you what it does three times: once in the doc comment, once in the function name, and once in the body.
Re:Why Not Comments by worik on Wednesday September 11, 2024 @03:46PM (#41514716)
Putting too much emphasis on na,Ed leads to looooong names

I've seen 64 character variable names

Names should be mnemonic. Reminding, not describing

Re:Why Not Comments by XorNot on Wednesday September 11, 2024 @04:41AM (#41509373)
This is what I tell people: if you're writing a one line code comment, write a debug log message instead.

There's vanishingly few cases where this extra logging statements will ever be a problem and they can all be handled autonomously if they ever are - but it will save everyone else a ton of time in deployment.

Re:Why Not Comments by kristiandupont on Wednesday September 11, 2024 @06:09AM (#41509859)
You must have extremely busy logs, then? Do you also do this with all the code that runs in loops?
Re:Why Not Comments by XorNot on Wednesday September 11, 2024 @06:38AM (#41510036)
Do you routinely run production services at debug or trace log level?

The point is there's a big difference between "we've got a problem, we need to add logging and redeploy to try and isolate it" versus "we might have a problem, bump the logging level up on that service to see what's going on" (which with the right system you can do without even restarting).

Re:Why Not Comments by kristiandupont on Thursday September 12, 2024 @06:08AM (#41519218)
No, I don't. But even when I turn debug/trace on, I want the logs to have a reasonable signal to noise level.
Re:Why Not Comments by __MatrixMan__ on Wednesday September 11, 2024 @03:03PM (#41514334)
I'm not who you're asking, but I do the same

Re: busy, no because I only enable debug logging when I need it

Re: loops, I wrote a deduplicating logger, so if there are 200 identical messages from within a loop I see:

    {event: "thing happened"}

    {event: "thing happened",
     duplicates: 100, 
     since: "2024-09-11T01:05:00Z",
     reason: "count reached"}
That is, supposing that it's set to saturate at 100 events and they all happen fast enough that it doesn't reset the count. In this case it'll log another batch of 100 on the 201st event.

I think it's important to log the first one immediately, just in case you want to alert on that message. It wouldn't do to wait for the other 99 before raising the alarm.

I wrap my loggers in deduplicators only when I'm about to hand them off to a loop. Otherwise it's the normal ones.