5 ms·

I comment everything that I think would be useful for me when revisiting the code a year later. Usually "why" and "why not". Sometimes a short "what" when the c

by narag 2y ago

I comment everything that I think would be useful for me when revisiting the code a year later. Usually "why" and "why not". Sometimes a short "what" when the code is complex and it's nice to see the sequence more clearly. What's not so useful: mandatory comments. A public API should be thoroughly documented, but some shops insist on writing comments for every function in the code, even private ones and even if its purpose is so obvious that the comment just rephrases its name. This practice is not only a waste of time, but also insensitizes you about comments and teach you to ignore them. Other wasteful comments are added by some tools. I hate the one that marks every loop wiht a //for or //try comment.

cjfd 2y ago
Yes, completely agree. Also, too many comments make it difficult to see what is in a class/function. If the comments make a class/function that would otherwise fit on one screen no longer fit on one screen there is a readability cost to this.
- exe34 2y ago
  I wish they would put the comments before the function name in python, as otherwise the useful code is separated by useless verbiage. I also wish comments would include examples of the shape and dtype of inputs and outputs.
- BeetleB 2y ago
  Collapsing/hiding comments should be a required feature in editors. In Leo[1], you can make nodes out of them and just hide them. If Emacs weren't so good, I'd be using Leo. Similar power when it comes to extensibility, but extended via Python, not elisp. [1] https://leo-editor.github.io/leo-editor/ https://leo-editor.github.io/leo-editor/
gwervc 2y ago
> Usually "why" and "why not" Related anecdote: yesterday I was on a code portion of a personal project with a "Is this really useful?" comment on a line that seemed it could easily be removed. I tried to use the newer and cleaner class instead and the particular old way was indeed needed. So I appended a "=> yes!" to the existing comment as well. I'm glad my former self documented the interrogation. At work, especially on bugfix, I often write a one or two lines comment with the ticket issue number over a non-obvious change.
- danadam 2y ago
  > So I appended a "=> yes!" to the existing comment as well. You will read it in 3 months and cry in despair "But why, my past self, why is it needed?!" :-)
  - zizee 2y ago
    Hopefully they recorded it in their commit log.
    - gwervc 2y ago
      Actually (I wanted to keep the story short), I added a new comment on the line before stating that the other way isn't working.
Cthulhu_ 2y ago
For some reason a lot of syntax highlighting color schemes de-emphasize comments, making them low contrast, which is probably because a lot of mandatory / generated comments are low information. Get rid of mandatory and generated comments, and change your color scheme to make them a bright neon colour instead (on a dark theme) to draw the attention, because IF something is commented then it's important.
- dizhn 2y ago
  I disagree with this. Comments are important but not every time you're in that part of the code. You might already know from just the code what's going on, or have already checked out the comments. There's no value to them always being emphasized. That would be like reading all NPC dialogs every time in an RPG.
  - bluGill 2y ago
    If there is a comment is should be important enough to read it every single time you are near that area of code even if looking for something else in the file! They should be a reminder of something important and not obvious in the code - otherwise I'll just read the code. Note that I distinguish comments from API documentation even though they are often both in the same code and use the same comment syntax.
    - qrobit 2y ago
      If there is something really important worth rereading over and over again, put «NOTE: » before it and let your editor highlight it for readers of your code
Attrecomet 2y ago
> Other wasteful comments are added by some tools. I hate the one that marks every loop wiht a //for or //try comment. Oh god, that's horrible, what kind of tool does that?!
- narag 2y ago
  I don't know, the guy is no longer around. Maybe some code-completion tool (write "for" and it completes the syntax) because it's all over the place.
  - b112 2y ago
    Eventually, we find out he wrote it all manually.
- skipkey 2y ago
  It was pretty common say 25 years ago when you would be developing in a terminal. When you were limited in the number of lines displayed, it sometimes made it easier to follow the code when functions and control structures were large. I know I had coworkers using brief configured to do that.
  - throwaway14356 2y ago
    i think it had something to do with indentation being all over the place.
harry_ord 2y ago
I find the why and what are so useful. If I know why what the code is aiming to achieve, it makes rewriting it or fixing a bug much easier
gspencley 2y ago
> 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.

by narag 2y ago

cjfd 2y ago

Yes, completely agree. Also, too many comments make it difficult to see what is in a class/function. If the comments make a class/function that would otherwise fit on one screen no longer fit on one screen there is a readability cost to this.

exe34 2y ago
I wish they would put the comments before the function name in python, as otherwise the useful code is separated by useless verbiage. I also wish comments would include examples of the shape and dtype of inputs and outputs.
BeetleB 2y ago
Collapsing/hiding comments should be a required feature in editors. In Leo[1], you can make nodes out of them and just hide them. If Emacs weren't so good, I'd be using Leo. Similar power when it comes to extensibility, but extended via Python, not elisp. [1] https://leo-editor.github.io/leo-editor/ https://leo-editor.github.io/leo-editor/

gwervc 2y ago

> Usually "why" and "why not" Related anecdote: yesterday I was on a code portion of a personal project with a "Is this really useful?" comment on a line that seemed it could easily be removed. I tried to use the newer and cleaner class instead and the particular old way was indeed needed. So I appended a "=> yes!" to the existing comment as well. I'm glad my former self documented the interrogation. At work, especially on bugfix, I often write a one or two lines comment with the ticket issue number over a non-obvious change.

danadam 2y ago
> So I appended a "=> yes!" to the existing comment as well. You will read it in 3 months and cry in despair "But why, my past self, why is it needed?!" :-)
- zizee 2y ago
  Hopefully they recorded it in their commit log.
  - gwervc 2y ago
    Actually (I wanted to keep the story short), I added a new comment on the line before stating that the other way isn't working.

Cthulhu_ 2y ago

For some reason a lot of syntax highlighting color schemes de-emphasize comments, making them low contrast, which is probably because a lot of mandatory / generated comments are low information. Get rid of mandatory and generated comments, and change your color scheme to make them a bright neon colour instead (on a dark theme) to draw the attention, because IF something is commented then it's important.

dizhn 2y ago
I disagree with this. Comments are important but not every time you're in that part of the code. You might already know from just the code what's going on, or have already checked out the comments. There's no value to them always being emphasized. That would be like reading all NPC dialogs every time in an RPG.
- bluGill 2y ago
  If there is a comment is should be important enough to read it every single time you are near that area of code even if looking for something else in the file! They should be a reminder of something important and not obvious in the code - otherwise I'll just read the code. Note that I distinguish comments from API documentation even though they are often both in the same code and use the same comment syntax.
  - qrobit 2y ago
    If there is something really important worth rereading over and over again, put «NOTE: » before it and let your editor highlight it for readers of your code

Attrecomet 2y ago

> Other wasteful comments are added by some tools. I hate the one that marks every loop wiht a //for or //try comment. Oh god, that's horrible, what kind of tool does that?!

narag 2y ago
I don't know, the guy is no longer around. Maybe some code-completion tool (write "for" and it completes the syntax) because it's all over the place.
- b112 2y ago
  Eventually, we find out he wrote it all manually.
skipkey 2y ago
It was pretty common say 25 years ago when you would be developing in a terminal. When you were limited in the number of lines displayed, it sometimes made it easier to follow the code when functions and control structures were large. I know I had coworkers using brief configured to do that.
- throwaway14356 2y ago
  i think it had something to do with indentation being all over the place.

harry_ord 2y ago

I find the why and what are so useful. If I know why what the code is aiming to achieve, it makes rewriting it or fixing a bug much easier

gspencley 2y ago

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