Generally, you can replace some comments with variable names or comment names. Which means you must already be in the habbit of extracting methods, setting new variables to use appropriate names, and limit context to reduce the name (Smaller classes and methods means shorter names can be just as expressive, because the context is clearer). It lowers the number of wtfs per minute you get reading code before you even need whole sentences to explain why things are done in a certain way, because the names can be a powerful hint.
But realistically, you end up needing comments for some things anyways.
Also some parts of code are just going to smell, because of deadlines, other trade offs. For those it helps to have a comment to really highlight that bit of weirdness - the what and the why. If it is weird it should really “pop out” when you’re reading it.
On one side you should put comments on the choices of how to do certain things at a code level that are the product of external limitations or requirements (over the years I’ve seen quite a lot of code which was kept doing things in a certain way and turned out the actual reason for it had long stopped being applicable) whilst most of the code should indeed be done to be self explanatory (though complex algorithms, especially if optimized or relying on obscure functionality, should probably be preceeded by a summary).
However, go up one level to software design and suddenly comments become more important (at the function and class level). They document functionality for significant chunks of code (so make it way faster for people trying to figure out the design of a code base they never saw before, as otherwise they would need to wade through a lot of code) as well as implied expectations in things like parameters or return values (i.e. that a variable is never expected to be null, that a zero size string is treated as NO DATA and so on) of functionality meant to be called from the outside (a kind of comment which is really just a lightweight form of an Interface Requirements Specification document). Mind you, over the years I’ve seen tons of comments documenting functions “just because” and without understanding what’s the point of doing it (probably because the programmers were told the HAD to do it) in the libraries and frameworks from some of the biggest companies around.
You could say the WHY of commenting is also important.
Yes, two of the most important things I see comments do is explain things like boundary conditions, “This is why we stop at 50 here.” and historical reasons “We have to return a 1 here because we still use calling func FOO for all of our calls still and it expects 1 as the default…”
Another helpful use is to describe the expected format of the input. “We expect a struct with this format here…” Stick in a small example too. It makes it so much easier to quickly scan the code’s flow.
Often you can find the “why” in the file’s Git history. If done properly, you should be able to find which commit introduced this change, and which issue is attached to this commit.
Yeah, good code should explain the “what” without the need for comments. Good comments explain the “why”.
Generally, you can replace some comments with variable names or comment names. Which means you must already be in the habbit of extracting methods, setting new variables to use appropriate names, and limit context to reduce the name (Smaller classes and methods means shorter names can be just as expressive, because the context is clearer). It lowers the number of wtfs per minute you get reading code before you even need whole sentences to explain why things are done in a certain way, because the names can be a powerful hint.
But realistically, you end up needing comments for some things anyways.
You sound like an awesome co-worker. I love the way this is stated, and I’m 💯 in alignment
Also some parts of code are just going to smell, because of deadlines, other trade offs. For those it helps to have a comment to really highlight that bit of weirdness - the what and the why. If it is weird it should really “pop out” when you’re reading it.
It’s a bit more complex than that.
On one side you should put comments on the choices of how to do certain things at a code level that are the product of external limitations or requirements (over the years I’ve seen quite a lot of code which was kept doing things in a certain way and turned out the actual reason for it had long stopped being applicable) whilst most of the code should indeed be done to be self explanatory (though complex algorithms, especially if optimized or relying on obscure functionality, should probably be preceeded by a summary).
However, go up one level to software design and suddenly comments become more important (at the function and class level). They document functionality for significant chunks of code (so make it way faster for people trying to figure out the design of a code base they never saw before, as otherwise they would need to wade through a lot of code) as well as implied expectations in things like parameters or return values (i.e. that a variable is never expected to be null, that a zero size string is treated as NO DATA and so on) of functionality meant to be called from the outside (a kind of comment which is really just a lightweight form of an Interface Requirements Specification document). Mind you, over the years I’ve seen tons of comments documenting functions “just because” and without understanding what’s the point of doing it (probably because the programmers were told the HAD to do it) in the libraries and frameworks from some of the biggest companies around.
You could say the WHY of commenting is also important.
Yes, two of the most important things I see comments do is explain things like boundary conditions, “This is why we stop at 50 here.” and historical reasons “We have to return a 1 here because we still use calling func FOO for all of our calls still and it expects 1 as the default…”
Another helpful use is to describe the expected format of the input. “We expect a struct with this format here…” Stick in a small example too. It makes it so much easier to quickly scan the code’s flow.
Often you can find the “why” in the file’s Git history. If done properly, you should be able to find which commit introduced this change, and which issue is attached to this commit.