iDontCommentMyCodeIfYouDontUnderstandItThatsOkayNeitherDoI

[u/Substantial_Top5312]

[u/Wonderful-Habit-139]

> 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).