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.
I used to work with a guy who insisted his code was self explanatory, and then he'd nest loops 5 levels deep and give variables names like "thingyOne".
I wonder if there's a warning for that in Clang or GCC. That seems like something I'd want, but also want it to be 100% opt-in. Not even enabled with -Wall or -Wextra.
I worked with a guy who was smart but “useless smart”. He was convinced that “code is self descriptive”, that is comments are not needed because the code speaks for itself. Well that is like saying DNA is self descriptive. Yes, I can sit there tracing the code, tracking the variables, etc or you could make a small effort to describe what is happening instead and save me a lot of time and risk missing subtle points.
I had a boss who hated comments because he wanted "clean code," and that comments means you aren't using the wiki. The build approval process actually stripped out all comments via a script.
For my own amusement I'm going to pretend you were using something like Perl where determining what's a comment and what's code can be context sensitive.
i.e. stripping from # to the end of the line can be a very wrong thing to do in a language where the comment marker can actually be used in other niche ways.
Strip the wrong "comment" and your code won't compile. Or worse, do something unexpected.
I agree with your team lead wholeheartedly, but not for the reasons he would tell you. Comments should be used when code is too complex for the "name your variables nouns and your methods verbs" convention doesn't communicate what the code does in a narrative fashion. Thing is, that level of complexity is definitely a code smell. You seem to be saying that clarifying comments are the solution, he seems to think that you should be able to rename vars and methods until the meaning is clear, and Im offering a third way: figure out why the fuck the code is doing something hard to understand and maybe try to unfuck it, then resort to comments if and only if that's not possible. Remember that a code smell isn't necessarily something that needs to be removed, it's just a flag that says "let's make double damn sure there isn't a better way to do this before we do it this way".
Yes, you don't need to comment "n++" to say it is incrementing it but you should mention why you are starting with 1 instead of 0, etc. Boundary conditions are notoriously tricky and need to be documented. Then there are historical reasons that are NEVER obvious, "This function has to return -2 as a default because we've been calling it using X for years and it expects a -1 as the error…"
this function returns -2 as success and -1 as error
Thats exactly the kind of thing I'm talking about when I say to prioritize refactoring over comments. If you own the system returning the error code, drag it out of the 1970s and have it return an error object with some actual information in it instead. If you don't own the system, wrap the error code in an enum that adds syntactic meaning or do a map of integer and exception and then return the mapped exception. The very last resort, after you've tried everything else, should be
I've worked on satellite command and control software that is literally using a 1970s OS. The code is limited for historical reasons and you have to work with the structure you are given.
okay. doesn't mean you still shouldn't refactor or add a layer of abstraction where you can. we're looking for a generalizable principle here and generalizable principles don't assume that you're working with satellites that are older than the dev.
Sometimes I just leave "feed it back to ChatGPT and ask to explain" sort of things xD.
This might not sound logical, but when you are writing Ansible for something that has no module or very complex - mix of Jinja2 templates and yaml tasks makes it superb hard, especially if you are looking for the first time.
Seriously, comments are useful, especially in top of the function.
I had so many arguments with my team lead. He thought comments were an antipattern because that meant the code wasn't expressive enough.
I understood where he was coming from, but a little hint here and there why the fuck the code is doing what it's doing would've been nice.
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.
I used to work with a guy who insisted his code was self explanatory, and then he'd nest loops 5 levels deep and give variables names like "thingyOne".
"thingyOne" is self explanatory, it's a thingy.
Namely, the first one. Next you're going to ask about thingySixtyNine or thingyOneHundredTwentyTwo, I suppose?
I don't know why you guys are so dense. How pedantic do thingiesNumX need to be?! It's perfectly obvious!
- Confucius
And turn signals are giving information to the enemy
Could be worse, it could've been customer_ID, Customer_id, customer_Id…
I wonder if there's a warning for that in Clang or GCC. That seems like something I'd want, but also want it to be 100% opt-in. Not even enabled with
-Wallor-Wextra.That guy wasn't in charge, I hope? That would not have passed code review with me at least.
I find that those people usually are the ones in charge.
He was.
Yup, he was in charge.
I worked with a guy who was smart but “useless smart”. He was convinced that “code is self descriptive”, that is comments are not needed because the code speaks for itself. Well that is like saying DNA is self descriptive. Yes, I can sit there tracing the code, tracking the variables, etc or you could make a small effort to describe what is happening instead and save me a lot of time and risk missing subtle points.
deleted by creator
I had a boss who hated comments because he wanted "clean code," and that comments means you aren't using the wiki. The build approval process actually stripped out all comments via a script.
Then we lost the wiki.
Thanks, Satan.
I'd watch the movie.
For my own amusement I'm going to pretend you were using something like Perl where determining what's a comment and what's code can be context sensitive.
i.e. stripping from
#to the end of the line can be a very wrong thing to do in a language where the comment marker can actually be used in other niche ways.Strip the wrong "comment" and your code won't compile. Or worse, do something unexpected.
It was all python, ruby, bash, and ansible
deleted by creator
It kind of feels like engineers look for simple solutions to what are ultimately complicated psychological questions sometimes.
deleted by creator
I agree with your team lead wholeheartedly, but not for the reasons he would tell you. Comments should be used when code is too complex for the "name your variables nouns and your methods verbs" convention doesn't communicate what the code does in a narrative fashion. Thing is, that level of complexity is definitely a code smell. You seem to be saying that clarifying comments are the solution, he seems to think that you should be able to rename vars and methods until the meaning is clear, and Im offering a third way: figure out why the fuck the code is doing something hard to understand and maybe try to unfuck it, then resort to comments if and only if that's not possible. Remember that a code smell isn't necessarily something that needs to be removed, it's just a flag that says "let's make double damn sure there isn't a better way to do this before we do it this way".
Yes, you don't need to comment "n++" to say it is incrementing it but you should mention why you are starting with 1 instead of 0, etc. Boundary conditions are notoriously tricky and need to be documented. Then there are historical reasons that are NEVER obvious, "This function has to return -2 as a default because we've been calling it using X for years and it expects a -1 as the error…"
Thats exactly the kind of thing I'm talking about when I say to prioritize refactoring over comments. If you own the system returning the error code, drag it out of the 1970s and have it return an error object with some actual information in it instead. If you don't own the system, wrap the error code in an enum that adds syntactic meaning or do a map of integer and exception and then return the mapped exception. The very last resort, after you've tried everything else, should be
return -1; //-1 indicates successI've worked on satellite command and control software that is literally using a 1970s OS. The code is limited for historical reasons and you have to work with the structure you are given.
okay. doesn't mean you still shouldn't refactor or add a layer of abstraction where you can. we're looking for a generalizable principle here and generalizable principles don't assume that you're working with satellites that are older than the dev.
Let me Guess, There is no added value in comments. Customer dont want to pay for comments, only for code that adds value.
Sometimes I just leave "feed it back to ChatGPT and ask to explain" sort of things xD.
This might not sound logical, but when you are writing Ansible for something that has no module or very complex - mix of Jinja2 templates and yaml tasks makes it superb hard, especially if you are looking for the first time.
Seriously, comments are useful, especially in top of the function.