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