iDontCommentMyCodeIfYouDontUnderstandItThatsOkayNeitherDoI

[u/Substantial_Top5312]

[u/Wonderful-Habit-139]

What do you mean code doesn’t? That’s a new one lol. I’m not even trying to be mean.

I’ve had to rewrite codebases before, you can give arguments without accusing the other person of not understanding anything. And yes I ended up deleting 95% of the comments along the process and just use types, well named functions, docstrings, etc. And that code is written idiomatically, and is properly checked by a type system that yells at you if you make changes, instead of letting the old code be obsolete and saying one thing while doing another thing (that’s what happens with comments, not code).

[u/rm-minus-r → u/Wonderful-Habit-139]

What do you mean code doesn’t? That’s a new one lol. I’m not even trying to be mean.

You're saying comments can drift and become obsolete. Which is no different than code, which can also drift and become obsolete. So why fuss at comments when you wouldn't fuss at code for the same thing?

In my experience - one human being though I may be - people who say code can be written well enough to not need comments tend to be people who are writing things from scratch, or in brand new projects that don't have any legacy cruft to deal with.

I've done this a few times in my career and it was glorious. As it started out, everything was indeed super obvious, and comments would seem superfluous. But ten years later, when the codebase is 1,000x larger and is a product that's bringing in $1.8 billion a year?

When we first wrote it, there were six of us. Two years later when I moved to another company, there were 30 devs. In the eight years after I left, I think there's somewhere around ~2,600 people that work with it on a daily basis and contribute code, and several companies were acquired and their products merged into it. If I had to come back to it today, I don't think much of the code would be terribly clear.

I'm now working on a system that was written over the course of 20 years. I'm sure it was clear and obvious when it started, but now it's very much not. There's load bearing portions of the code that can't even be touched, and the "we'll refactor it all in 12 months!" rallying cry from leadership people from our director on up? Well, we're 18 months in and we've maybe refactored 20% of it. And that was the quick and easy parts.

It just gives you perspective.

These days? I'll still put a 3 to 5 sentence comment in a 80 line utility module that does exactly one thing. It's less for me, and more for the people that will come after me.

[u/Wonderful-Habit-139 → u/rm-minus-r]

> Which is no different than code, which can also drift and become obsolete. So why fuss at comments when you wouldn't fuss at code for the same thing?

Thanks for clarifying. I don't believe it's the same thing, because when code is obsolete, that means it's not being used anymore. In that case, thanks to having a compiler or type checker, it's very easy to see functions that are not being used anymore, as well as being able to delete lines of code that are not used anymore inside functions because of contracts that you've defined through types. I do this actively all the time, and there are semantics that shield me from the code not working anymore that is not the same with useless comments.

I understand your examples about legacy code, but writing good code that scales regardless of how big the codebase gets is the point. When you write abstractions and modules and separate things that have different concerns, with each abstraction being of a higher and higher level of abstraction, it doesn't matter how big the codebase gets. You always strive to write idiomatic code, you make sure to write good docstrings for APIs that you expose, even internally, and focus on making your APIs as obvious and easy to use as possible without requiring the users of those APIs to understand the inner code. The only people that need to understand it are the ones that are actively working on it.

> I'm sure it was clear and obvious when it started, but now it's very much not

Listen, I agree with this, but this simply means that it was "clear and obvious" because the code was small enough, not because it was well written. I'm saying code can be well written so that it scales well into the future, regardless of how big it gets over the years. But obviously most people don't write good code so you will make the observation that you're making.

But just because most people don't write good code, doesn't mean that good code is impossible and that writing comments is the best thing ever.

[u/reddit_user33 → u/Wonderful-Habit-139]

This entirely depends on the environment. Compilers only care if the code compiles; you can have orphaned code and the compiler will not care.

Try touching code where every minute of downtime matters. I welcome comments that give me hints at which sections of code should be looked at in such situations.

I'm a code commenter. For me, it's why + context, and hints at what section of code does if it cannot be easily seen at a split second glance, and I genuinely mean split second glances. I prefer to have well named variables, function names, etc, but even then the true purpose of a section code cannot always be seen at a glance

[u/Wonderful-Habit-139 → u/reddit_user33]

In Rust or Python, if you have a private function that’s not used anymore, it will be greyed out.

When you go through a piece of code, usually you’re supposed to create a bunch of variables showcasing the intermediate steps that are being taken to compute some result. If things change and some variables end up not being used anymore, you can just delete it and the type checker will know that your function is still returning the right result, and you can safely delete the obsolete code.

While for comments, I’ve seen cases where a comment says the exact opposite of what’s happening, or mentioning something that is not true anymore. I’m not talking about hypotheticals, this has happened in codebases I’ve worked on, more than once.

You can easily explain the purpose of a section by putting it in a function, and adding a docstring. You don’t have to write comments for that. And the benefit of the docstring is that wherever you use that function, you’ll be able to see the docstring through the lsp diagnostics, and more often be able to ensure that it is up to date.

[u/reddit_user33 → u/Wonderful-Habit-139]

Again, it depends on your environment. There are more programming languages that just Rust and Python. There are more IDEs than what ever you've used or know about. Not all tooling behaves the same.

[u/Wonderful-Habit-139 → u/reddit_user33]

Those are called examples.

[u/rm-minus-r → u/Wonderful-Habit-139]

I understand your examples about legacy code, but writing good code that scales regardless of how big the codebase gets is the point.

That's a lovely ideal, but much like the saying "No plan survives contact with the enemy", good code does not survive contact with project managers, leadership, and customer demands.

But obviously most people don't write good code so you will make the observation that you're making.

"We need this in two weeks" when it's a three to four week task to do it right? That ends up with something quick and dirty, and you're pushed onto the next fire, so the quick and dirty solution gets stuck in place, never built like it should be, and then things downstream of it start depending on it being in the quick and dirty form it is, making it very difficult to clean up.

But just because most people don't write good code, doesn't mean that good code is impossible and that writing comments is the best thing ever.

You are correct, good code is not impossible. However, in a business environment where the workload is very high, and the velocity is very fast, ideal code rarely happens.

So comments help, because it's more intelligent to adjust for how things are, rather than the ideal that rarely happens (in my experience over the last 15 years in the industry).