Comment your code? Nah. If it was hard to write, it should be hard to read.

Oldie but goldie.
I hate the implied messages here on many levels but I won‘t over analyze the joke :)

Years ago senior programmer complained to me that the interns w/ whom he'd been working were either !commenting the code, or insufficiently commenting it.

I made a joke that he should give me SVN access to the project, so that I could point out to them what I don't understand, therefore those parts need to be commented.

/* The implication being... pretty much all of the code. */

Made him laugh... but yeah... commenting is good.

...otherwise, eventually this happens: https://monkeyuser.com/2018/... .

/* Damn it, dug up the comic too late to edit previous comment. */

@D-4got10-01 no, it‘s not.

Commenting shit code to make it better is like covering cracks in the wall with a layer of paint.
It only hides the issue and will cause more problems in the long run.

Refactor the the code, use proper names, extract magic numbers into variables. Make your fucking code readable and you don’t need comments which lie to you and go out of sync with the code.

God damnit why does this need to be explained over and over again?

Sorry, but this triggers me way too hard.

@Lensflare Hmm, also a good take - heard it before, but it must've slipped my mind. I'd think sometimes there's a need for weird / inventive / convoluted solution. At those times, commenting seems like a good idea.

Although yeah, if comments lie to you, that's bad.

@Lensflare Hmm... just remembered a good argument for comments.

Have you seen 'War Stories', by any chance? Like for example the one about 'Crash Bandicoot':

https://youtube.com/watch/... .

While he's !talking about commenting code, w/ time, you might forget why you chose to do x instead of y. So sometimes it's about having a reminder of why you did something instead of how it works.

@D-4got10-01 yeah, comments are allowed for rare cases where it makes sense, but if you comment on every line of code saying what that line does, then you should be beaten with a rubber dick! No offense! 😂

@Lensflare how do you recognize a friendly German motor driver? 😁

@Lensflare Even good code should be commented

Many people just don't know how to write good comments! You shouldn't just reiterate what the code already tells you itself. Instead, comments should give additional context and insight why you did something, or how it slots into the big picture or a summary of what you're doing so you don't have to read 200 lines of code to know what a loop does

@12bitfloat yes, exactly. And when you apply that, comments should become rare automatically.

@whimsical I don’t know… he greets you by raising his right hand?

@Lensflare No, because good comments are orthogonal to good code. And splitting everything up into tiny self-describing functions (aka "clean code") to compensate for the lack of comments is imo pretty horrible and makes code less readable

I take a 300 line function with good comments over 30 ten line functions every day of the week. The former can be read sequentially, and thanks to comments you can skip big chunks of code to find what you need. The latter requires jumping around all the time, repeating variables for parameters, etc.

Coding horror. :coding_horror_emoji:

@12bitfloat I get your point and I agree. However, the cases where code is actually more readable in your 300 loc example are extremely rare in my experience. They exist, but most of the time it makes absolute sense to split functionality into smaller functions.
It improves readability.
You don’t need to read the whole thing and in the right order to understand what a function does. Hiding details in smaller functions reduces the required cognitive load. And if you are interested in a particular function, you can selectively jump in and read it, instead of having to scroll through a wall of text to skip crap that you are not interested in.

…

@12bitfloat

…

It‘s not like you should just start extracting code into smaller functions just for the sake of making the overall function smaller in size.
No, it‘s just that large functions are almost always the result of spaghetti and scream for structuring and organization. It makes the code more dry, more composable, maintainable, testable, and easier to reason about.

@Lensflare That's the conventional wisdom and I don't necessarily disagree with it. Especially when it comes to DRY, I'm pretty anal about that

Maybe I'm just biased against "clean code" (it badly burned me), but I've always hated my code. Now I write very pragmatic YAGNI code and I absolutely love it. But idk ¯\_(ツ)_/¯

I realise this is wayy off the OP but I hope you guys don't mind

@Lensflare "large functions are almost always the result of spaghetti" - I kinda agree but at the same time, after reading the horrendous code examples in the book 'Clean Code' I gotta say if I would be forced to pick between two bad codebases: one with tons of small functions and one with a few large functions I might pick the one with large functions, cause it is kinda easy to debug a few mega functions. But it can be hellish to debug a huge call stack of 30 similarly named functions, and to find out if any of them is actually re-used elsewhere or not and if their arguments matter.

EDIT: Of course these are insane examples. The ideal is a mix of tiny reusable functions and maybe mid-sized one-off-functions but ..still

@12bitfloat
@Lensflare

I said this before. Will say again. We all can read code. We can not read intent. Comment intent, not just blindly repeating what code evidently does.

Sure, if you use some obscure technique like quake fast sqrt by all means comment.

In the end, it's all about being able to put yourself in the shoes of anyone new to your project.

In nVidia, it's enforced that anything that is pushed must build, and our AI assistant can actually tell (because it analyzes frequency of use and such) whether what you implemented is easy enough to maintain.

It only flags when it doesn't understand what we try to do, and forces us to comment (again, intent) the AI has a compiler, and therefore knows better than us what code is trivial and what is doing esoteric shit