9 ms·

My commenting guidelines learned after nearly 40 years of programming: - One short sentence comment for every function consisting of more than 5 or so lines of

My commenting guidelines learned after nearly 40 years of programming: - One short sentence comment for every function consisting of more than 5 or so lines of code. Keep it short. Note anything deviating from someone's expectations of the function. - Comment high level process flow. I don't need a blow-by-blow. For the love of all that's holy please, please, please don't tell me you're incrementing i! Keep it terse and high level. - If something is done differently than an experienced person would expect it to be then document why it's being done that way. You can write a book and that's okay. I'm old enough to remember when both CPUs, OS's, and compilers had bugs and sometimes you had to do some strange-looking workarounds. Document them - thoroughly! Other than that I agree with the "let the code speak for itself crowd." Based off my rules excessive code comments are a code smell needing to be checked out.

war1025 6y ago
> Based off my rules excessive code comments are a code smell needing to be checked out I don't know that I fall into the "excessive" category, but I do tend to comment method bodies fairly heavily. Basically my strategy is: Add comments in the places someone is going to ask a question about in review. If you answer all their questions ahead of time, then you save them time, and you also save yourself time next time there is a bug or refinement in that code. I generally keep things fairly high level though. Some people advocate for breaking anything longer than X lines out into its own method. What I tend to do instead of wrap blocks of code like (Python): #{ <section descriptor> ... ... #} That way it's easy to follow the flow of things even if they get a little long.
- t-writescode 6y ago
  When the function gets sufficiently long and with sufficiently numerous 'arcs' (different bundles of if-statements that may be triggered under different conditions), how do you test the code change you're making? Would testing it be easier if it were broken out further?
  - war1025 6y ago
    > Would testing it be easier if it were broken out further? In my experience, you get the most effective use of your time by testing at interface boundaries. How the code is structured inside of those doesn't terribly matter in most cases. That said, you are almost always better off structuring a method as a linear set of steps rather than trying to turn it into some sort of "choose your own adventure" journey. Basically a typical method of the sort I'm thinking of would be something like: #{ Check early out conditions ... #} #{ Prepare the values ... #} #{ Perform I/O operation ... #} #{ Clean up / build return value ... #} You could break that out into four or five methods, but most likely the contents are going to be a bit of filler and then calling into some other library. Easier to keep everything consolidated and avoid the spaghetti.
    - t-writescode 6y ago
      This method already looks like it’s been reasonably shrunk to a single unit, unless “prepare values” is a lot of business logic; and, you’re already past all the major conditional checking. Fair enough.
    - wulouis0511 6y ago
      Neat idea, but I'd like to know how do you deal with nested block.
      - war1025 6y ago
        Usually I will just add the same sort of thing at nested levels. Thinking on it more, the purpose of the `#{` `#}` is to denote "This comment is relevant for this section of code"
    - joshuamorton 6y ago
      If each section is only a few lines, you've doubled your function length without giving any context relevant to someone who has written code before. If those are long/complex enough that you need to keep track of the sections individually, yeah break them out! Like, what insight does "perform io operation" provide beyond what f.write() already gives?
forgotmypw17 6y ago
I comment for myself first. In my experience, I may not remember what the heck I was thinking writing that code even 5 minutes later. If I ever start wondering what my code is supposed to do, once I figure it out, I comment. After doing this for a while, I've learned what I'll probably want to know later, and what will seem obvious. Besides this addition, I think your outline hits the nail on the head.
- anon9001 6y ago
  I agree with all of that. It sounds silly, but if you can work how you feel into the comment, it's really helpful later on. I like to use tags and sometimes emojis. Just remember that you're talking to future you. Usually specific versions of these: * `// XXX this is a bad thing that we can't improve yet, sorry` * `// TODO this thing works, but it should also do something else soon` * `// FIXME this is definitely broken` * `// HACK here comes some magic stuff, but it works...` * `// NOTE this is non-traditional or non-obvious, so let me explain` If you do that, it makes it easy to search for tech debt too.
- barry27 6y ago
  i agree with all of this too. i'd also add that sometimes the comments are there before the code, as i attempt to explain to myself what's going to happen next.
SiVal 6y ago
Well, FWIW after decades of programming, I find it useful to include a lot of comments. I also find that they get in my way. If you've ever read "Programming Pearls", you've seen how code that looks fine can have all sorts of subtle issues. In my experience, this is common, not rare. We just miss most of it. When I go back over code I've written, I see new things every time, sometimes because I've used the code in practice (different in various ways from what I expected), sometimes just with "fresh eyes", sometimes with "newbie eyes" ("Why would I do B before A..?"). I notice things I missed before. I miss things I noticed before. And very often bugs exist because I didn't think of something. As soon as I think of it, it's not enough to eliminate it in code and pretend I was right all along, I want to leave a note pointing out the thing I overlooked, even though it might sound obvious when stated. Etc. So many little things I learn about the code over time. I can write them down or leave future readers to the whims of fate. If I'll be the future reader, I write them down right where they are most relevant. I also want to be able to glance over my code and quickly know exactly how it works. I don't want to figure anything out if it can just remind me. So, yes, definitely my comments are higher level than the code, to make them quicker to comprehend at a glance, but they sometimes drop down from the "why" into the "how". So then, I have lots of useful comments that for my own code, I'm definitely going to keep. But the comments accumulate as the knowledge accumulates, and it can become annoyingly cluttered. Sometimes I want to see them, and sometimes I don't. (I always try to find ways for the code to "absorb" some of my comments, breaking a composite expression into steps with explanatory variable names, for example, but there are still lots of comments.) So, I want more sophisticated showing and hiding of comments from my code editor. I want to click a key and make all comments vanish. Nothing but the code, neat and tidy. Another click, and I see abbreviated comments, remember this, watch out for that, consider whatever.... Then maybe a mouse click on a link in one of the comments to bring up more details. Ah, yes. Key click, and all comments gone again. VS Code, I'm hoping....
- drothlis 6y ago
  It’s sometimes more than one click, but “git blame” (built into the IDE) serves that purpose for me.
  - 6y ago
baq 6y ago
i agree in general. i've only got ~15 years of professional experience, but: - code says how it's done - comments say why it's done - comments say why something isn't done - comments say how to use the damn thing - comments say who thought it was a good idea to implement the damn thing - answers to above questions are usually provided in code review as replies and actually should be comments in code
- mikeyjk 6y ago
  Agree except for the 'who', that sounds like it should be in the work tracking system (e.g. JIRA) rather than comments in code.
  - baq 6y ago
    but then, see the point about work tracking systems being outside of source history and thus prone to migration failures, etc. also, git blame sort of fills this role, but the commit author may not be the person who acked the implementation and requires digging in history if there were any refactorings done.
- rags2riches 6y ago
  I'd expand the first item to NAMES say how it's done. Need it to be clearer? Add more intermediate vars and functions with good informative names.

war1025 6y ago

> Based off my rules excessive code comments are a code smell needing to be checked out I don't know that I fall into the "excessive" category, but I do tend to comment method bodies fairly heavily. Basically my strategy is: Add comments in the places someone is going to ask a question about in review. If you answer all their questions ahead of time, then you save them time, and you also save yourself time next time there is a bug or refinement in that code. I generally keep things fairly high level though. Some people advocate for breaking anything longer than X lines out into its own method. What I tend to do instead of wrap blocks of code like (Python): #{ <section descriptor> ... ... #} That way it's easy to follow the flow of things even if they get a little long.

t-writescode 6y ago
When the function gets sufficiently long and with sufficiently numerous 'arcs' (different bundles of if-statements that may be triggered under different conditions), how do you test the code change you're making? Would testing it be easier if it were broken out further?
- war1025 6y ago
  > Would testing it be easier if it were broken out further? In my experience, you get the most effective use of your time by testing at interface boundaries. How the code is structured inside of those doesn't terribly matter in most cases. That said, you are almost always better off structuring a method as a linear set of steps rather than trying to turn it into some sort of "choose your own adventure" journey. Basically a typical method of the sort I'm thinking of would be something like: #{ Check early out conditions ... #} #{ Prepare the values ... #} #{ Perform I/O operation ... #} #{ Clean up / build return value ... #} You could break that out into four or five methods, but most likely the contents are going to be a bit of filler and then calling into some other library. Easier to keep everything consolidated and avoid the spaghetti.
  - t-writescode 6y ago
    This method already looks like it’s been reasonably shrunk to a single unit, unless “prepare values” is a lot of business logic; and, you’re already past all the major conditional checking. Fair enough.
  - wulouis0511 6y ago
    Neat idea, but I'd like to know how do you deal with nested block.
    - war1025 6y ago
      Usually I will just add the same sort of thing at nested levels. Thinking on it more, the purpose of the `#{` `#}` is to denote "This comment is relevant for this section of code"
  - joshuamorton 6y ago
    If each section is only a few lines, you've doubled your function length without giving any context relevant to someone who has written code before. If those are long/complex enough that you need to keep track of the sections individually, yeah break them out! Like, what insight does "perform io operation" provide beyond what f.write() already gives?

forgotmypw17 6y ago

I comment for myself first. In my experience, I may not remember what the heck I was thinking writing that code even 5 minutes later. If I ever start wondering what my code is supposed to do, once I figure it out, I comment. After doing this for a while, I've learned what I'll probably want to know later, and what will seem obvious. Besides this addition, I think your outline hits the nail on the head.

anon9001 6y ago
I agree with all of that. It sounds silly, but if you can work how you feel into the comment, it's really helpful later on. I like to use tags and sometimes emojis. Just remember that you're talking to future you. Usually specific versions of these: * `// XXX this is a bad thing that we can't improve yet, sorry` * `// TODO this thing works, but it should also do something else soon` * `// FIXME this is definitely broken` * `// HACK here comes some magic stuff, but it works...` * `// NOTE this is non-traditional or non-obvious, so let me explain` If you do that, it makes it easy to search for tech debt too.
barry27 6y ago
i agree with all of this too. i'd also add that sometimes the comments are there before the code, as i attempt to explain to myself what's going to happen next.

SiVal 6y ago

Well, FWIW after decades of programming, I find it useful to include a lot of comments. I also find that they get in my way. If you've ever read "Programming Pearls", you've seen how code that looks fine can have all sorts of subtle issues. In my experience, this is common, not rare. We just miss most of it. When I go back over code I've written, I see new things every time, sometimes because I've used the code in practice (different in various ways from what I expected), sometimes just with "fresh eyes", sometimes with "newbie eyes" ("Why would I do B before A..?"). I notice things I missed before. I miss things I noticed before. And very often bugs exist because I didn't think of something. As soon as I think of it, it's not enough to eliminate it in code and pretend I was right all along, I want to leave a note pointing out the thing I overlooked, even though it might sound obvious when stated. Etc. So many little things I learn about the code over time. I can write them down or leave future readers to the whims of fate. If I'll be the future reader, I write them down right where they are most relevant. I also want to be able to glance over my code and quickly know exactly how it works. I don't want to figure anything out if it can just remind me. So, yes, definitely my comments are higher level than the code, to make them quicker to comprehend at a glance, but they sometimes drop down from the "why" into the "how". So then, I have lots of useful comments that for my own code, I'm definitely going to keep. But the comments accumulate as the knowledge accumulates, and it can become annoyingly cluttered. Sometimes I want to see them, and sometimes I don't. (I always try to find ways for the code to "absorb" some of my comments, breaking a composite expression into steps with explanatory variable names, for example, but there are still lots of comments.) So, I want more sophisticated showing and hiding of comments from my code editor. I want to click a key and make all comments vanish. Nothing but the code, neat and tidy. Another click, and I see abbreviated comments, remember this, watch out for that, consider whatever.... Then maybe a mouse click on a link in one of the comments to bring up more details. Ah, yes. Key click, and all comments gone again. VS Code, I'm hoping....

drothlis 6y ago
It’s sometimes more than one click, but “git blame” (built into the IDE) serves that purpose for me.
- 6y ago

baq 6y ago

i agree in general. i've only got ~15 years of professional experience, but: - code says how it's done - comments say why it's done - comments say why something isn't done - comments say how to use the damn thing - comments say who thought it was a good idea to implement the damn thing - answers to above questions are usually provided in code review as replies and actually should be comments in code

mikeyjk 6y ago
Agree except for the 'who', that sounds like it should be in the work tracking system (e.g. JIRA) rather than comments in code.
- baq 6y ago
  but then, see the point about work tracking systems being outside of source history and thus prone to migration failures, etc. also, git blame sort of fills this role, but the commit author may not be the person who acked the implementation and requires digging in history if there were any refactorings done.
rags2riches 6y ago
I'd expand the first item to NAMES say how it's done. Need it to be clearer? Add more intermediate vars and functions with good informative names.