4 ms·

> I comment everything that I think would be useful for me when revisiting the code a year later. Do you code solo or do you work with a team? If so, how large

> I comment everything that I think would be useful for me when revisiting the code a year later. Do you code solo or do you work with a team? If so, how large is the largest team you've worked with? I used to be a dogmatic "all comments are code smells" person and, to a large degree I still am. But working on a very (and I mean VERY) large code-base that is actively developed and maintained by hundreds of other software developers, I have relaxed my position slightly into the "if you need to do something weird, explain why" ... because a large legacy system that lives in a business environment of tight deadlines means that there are often weird things that need to be done to keep things moving at a pace that the business is willing to pay for. Anyway, one of the many reasons that I argue AGAINST code comments is that the comments become part of the code and therefore require maintenance. But few people read comments unless they are stuck trying to understand something. This "psychological invisibility" is even enforced by the fact that most code editors will grey out comments in order to make them less distracting. And therefore, comments can easily become outdated. So I'm curious about your situation. Since you say that you like to give yourself useful context for "future you", what context does this process serve? Do you find it useful when working on a shared codebase with lots of other developers? Or is it something that only works well when there are few developers touching the code?

mplewis 2y ago
Comments that I leave for myself help remind future-me why I did something that otherwise looks confusing.
ziml77 2y ago
I think color schemes that make comments nearly invisible are just bad. Visual Studio's default color schemes have it right. Comments are not treated as lesser than anything else. As long as they aren't being placed every couple of lines they shouldn't really be a nuisance when reading through code. And to me not updating the comments is the same as not updating the name of a variable when its purpose changes. The compiler doesn't care that you didn't update the name, but people reading the code do. Also when it comes to "future you", you basically should think of yourself in the future as a different person. Because unless you are constantly working with the same bits of code, you will forget details and possibly even the high-level.
RHSeeger 2y ago
> And therefore, comments can easily become outdated. I am firmly of the opinion that keeping the comments up to date is part of the job of the developer. And if they're not doing it, they're not doing their job. It's no different than taking the time to write code that does the right thing, expresses the intent of what it's trying to do, etc. And, when code is peer reviewed, not including/updating comments in places where they are important should be a reason to send the code back to the developer. I feel the same way about automated testing. They're both (testing and comments) way to make our code better; easier to understand, easier to maintain, more likely to be correct, etc.
- makeitdouble 2y ago
  > I am firmly of the opinion that keeping the comments up to date is part of the job of the developer. I see where this comes from, but practicality is a huge issue. Comments don't become obsolete just by laziness, but also because they are human targeted and can't easily be managed the same way code is. For instance if you comment on a function call to explain it's needed because of its side effects, when the function gets fixed and loses that side effect your comment becomes obsolete. Will the person fixing the inner function go back to every single comment that vaguely references it's behaviour and fix them ? And do they also go to the one-up parent function to check the comments there ? If we're assuming large orgs with expansive code bases, it's just not realisitic to be dealing with all that prose and maintain consistency when what you're modifying can be mentioned anywhere is any tangential way.
  - RHSeeger 2y ago
    > For instance if you comment on a function call to explain it's needed because of its side effects, when the function gets fixed and loses that side effect your comment becomes obsolete. And if you have a function call in your code that doesn't look like it does anything and don't comment it, then you're doing it wrong. And if the person who wrote `functionWithSideEffects` changes it to not have side effects anymore, and the places that call it for the side effects don't get updated then, once again, someone isn't doing their job. Keeping comments up to date is no different than keeping code up to date, or tests up to date, or removing code that isn't needed anymore, or cleaning code up so it doesn't turn into spaghetti, or anything else we do as developers. Does it always get done? Of course not. But that doesn't mean it shouldn't get done.

mplewis 2y ago

Comments that I leave for myself help remind future-me why I did something that otherwise looks confusing.

ziml77 2y ago

I think color schemes that make comments nearly invisible are just bad. Visual Studio's default color schemes have it right. Comments are not treated as lesser than anything else. As long as they aren't being placed every couple of lines they shouldn't really be a nuisance when reading through code. And to me not updating the comments is the same as not updating the name of a variable when its purpose changes. The compiler doesn't care that you didn't update the name, but people reading the code do. Also when it comes to "future you", you basically should think of yourself in the future as a different person. Because unless you are constantly working with the same bits of code, you will forget details and possibly even the high-level.

RHSeeger 2y ago

> And therefore, comments can easily become outdated. I am firmly of the opinion that keeping the comments up to date is part of the job of the developer. And if they're not doing it, they're not doing their job. It's no different than taking the time to write code that does the right thing, expresses the intent of what it's trying to do, etc. And, when code is peer reviewed, not including/updating comments in places where they are important should be a reason to send the code back to the developer. I feel the same way about automated testing. They're both (testing and comments) way to make our code better; easier to understand, easier to maintain, more likely to be correct, etc.

makeitdouble 2y ago
> I am firmly of the opinion that keeping the comments up to date is part of the job of the developer. I see where this comes from, but practicality is a huge issue. Comments don't become obsolete just by laziness, but also because they are human targeted and can't easily be managed the same way code is. For instance if you comment on a function call to explain it's needed because of its side effects, when the function gets fixed and loses that side effect your comment becomes obsolete. Will the person fixing the inner function go back to every single comment that vaguely references it's behaviour and fix them ? And do they also go to the one-up parent function to check the comments there ? If we're assuming large orgs with expansive code bases, it's just not realisitic to be dealing with all that prose and maintain consistency when what you're modifying can be mentioned anywhere is any tangential way.
- RHSeeger 2y ago
  > For instance if you comment on a function call to explain it's needed because of its side effects, when the function gets fixed and loses that side effect your comment becomes obsolete. And if you have a function call in your code that doesn't look like it does anything and don't comment it, then you're doing it wrong. And if the person who wrote `functionWithSideEffects` changes it to not have side effects anymore, and the places that call it for the side effects don't get updated then, once again, someone isn't doing their job. Keeping comments up to date is no different than keeping code up to date, or tests up to date, or removing code that isn't needed anymore, or cleaning code up so it doesn't turn into spaghetti, or anything else we do as developers. Does it always get done? Of course not. But that doesn't mean it shouldn't get done.