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

@Lensflare Ah, yes. Commenting _every_ line would be an overkill. It would produce more clutter than anything of value.

@Lensflare > '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! 😂

Actually... you've reminded me of this one... https://devrant.molodetz.nl/preview... .

Shh... don't judge && keep that rubber dick away from me.

/jk

OK, so this was a school assignment from years ago. Teacher did ask for comments... probably to check whether we knew what we had been doing.

I fully realize, now, that this looks like an abomination.

@Lensflare nope. Self documenting code is a myth. Comments are for context.
Code is always functional. That means that you can only convey so much. Especially when optimized. Even with the greatest names a lot of people need a dictionary or don't understand the overarching concept or actual real world issue.

For example I had to make a financial field modified 4 eye process. However the international product number is also included. While this field has no impact on the financial status of the product. It could be used to commit fraud.
Without the comment that it indeed has possible financial impact it's the odd one out and might be removed in a cleanup.

Of course i could create specific fiction that returns the ID but name it possibleCheapProductFraudField. But that breaks other good naming/coding practices and makes shit more convoluted.

@CoreFusionX that's both kinda cool and possibly very annoying. I fully agree with the first part as you can see from my comment (wrote it before I saw yours)

@hjk101 again, I‘m not advocating for banning comments. Just use comments correctly, to convey meaning and to explain things that are difficult to explain via code, like the example that you given.
But most code is freaking obvious. Writing comments for it is completely unnecessary.
And if you write it to explain the meaning of the variable and function names (as many do), rename your variable or function instead.

Breaking a naming convention to better explain a thing is much better than to add a comment.

@hjk101

It's basically a glorified linter, but it has context from the internal issue tracker and chat so it's trained on what trips other devs in the team and kinda checks for that too. Not really more annoying than your usual code review, except it's a machine, doesn't have feelings, doesn't hold grudges, and can trust it's not out to get you and annoy you no matter what.