5 ms·

One way to cap the cognitive load of adding and maintaining comments is to limit them to explain why a piece of code does what it does, rather than how. Rely o

One way to cap the cognitive load of adding and maintaining comments is to limit them to explain why a piece of code does what it does, rather than how. Rely on the fact that the how is self-documenting to other programmers who may need to maintain your code later (including you), but the why is not always so. Eg, were other options considered and this one chosen? Why? Is this piece of code non-standard or particularly clever? Why? Is this piece of code more complex than it seems like it needs to be? Why? Does this piece of have non-local dependency that may not be obvious at first glance? Are there security concerns with this piece of code which are non-obvious to a novice or an outsourced worker? Etc. There's the old saying, "since debugging code is more difficult than writing it, then if you write the most clever code you are capable of, then you are by definition incapable of debugging it". Pretend you're explaining your code to future you who has forgotten why you did what you did and isn't clever enough to debug it.

fishtoaster 4y ago
I think "why" comments are the most useful, but "what" comments are a bit undervalued. A few types of "what" comments are, I find, very useful: 1. Comments that are effectively headers: # If the user is foobar, do thing user = User.find(current_user_id) user.preload_bizbaz!(cache: false) is_foobar = user.bizbaz.foobar.status == "yes" if (is_foobar) { do_thing(user) } Yes, you can read the 4 lines of code to see the "what' - the comment is duplicative. But when I'm skimming through a large codebase trying to find or understand something, these headers can be invaluable. 2. Comments on dense code # Matches any email like foo@bar.com (only .com, .net, .org email addresses) return email.match(/^.*@.*\.(com|net|org)$/) Yes I can that regex, but I can read that comment a lot faster.
- vikingerik 4y ago
  And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it.
  - Arrath 4y ago
    Next up: comments that dynamically generate from the code itself, like tooltips in a game. /s "...only from %s domains..."
    - mr_toad 4y ago
      Like GPT in reverse? I wonder how long it will take before someone tries to use an AI to document code.
  - tablespoon 4y ago
    > And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it. That always gets trotted out, but it's sort of like "don't write code unless you can guarantee the code won't have any bugs, so never write any code." The trick is write code and comments, but be a little skeptical of both. If you're disciplined (especially with commit messages), it's usually pretty easy to figure out a mistake or omission after the fact.
- coryrc 4y ago
  Those are perfect examples of what not to do.
- ezkhimo 4y ago
  For your first example, use a method with a fitting name. Second one is not a good example, because I think it's a very common pattern and email.match with com|net|org provides enough context by itself. It's just bloat imo.
- m000 4y ago
  I love header comments, but many people fail to get their usefulness, and I get the "good code does not need comments" mantra recited to me pretty often. Here is the thing: Header comments are not really about explaining their following code. They are about reducing the lines you need to read to navigate through the code by a factor of 5 to 10. Huge time-saver, and helps a ton newcomers to become productive quickly.
- raytracer 4y ago
  I like header comments too, but I almost never use them when working on a team. I feel like there are a bunch of coding habits that work well for solo developers but not devs on a team.
- tablespoon 4y ago
  > I think "why" comments are the most useful, but "what" comments are a bit undervalued. A few types of "what" comments are, I find, very useful: I agree. However, "what" comments need a little more skill and judgement to know what to write and what to leave out. Having a terrible memory helps develop that skill, because you kind of get a sense of what you'll want explained to you again in six months and what's hard to decode.
- amalcon 4y ago
  My favorite type of "What" comment is: // The following block should have the same // result as this (simpler) code: // <code> // but for <reason> this version is better This is great for things like opaque optimizations, things that mimic a library function except for one critical difference, blocks that become really convoluted to deal with special cases, and similar.
- osigurdson 4y ago
  >> Yes I can that regex, but I can read that comment a lot faster. Regex is the worst language that everyone needs to know.
  - Raidion 4y ago
    I like the joke "if you decide to use regex to solve a problem, you now have two problems"
- MaurizioPz 4y ago
  1. would be better as a function, so you have: - a nice explanatory name to it - if the functionality changes then it is more probable that the name would change - the code is hidden away if you don't care about the why (maybe you are looking for something else)
- rkangel 4y ago
  I am 99% in agreement with everything you said, so of course I'm going to focus on the 1%! If you have a 4 line stanza that needs a comment to explain what it's doing then I'd suggest that needs breaking out into a function so that your code then becomes `if (is_foobar?(current_user_id)) {do_thing()}`. Just as readable with no comments needed. There are definitely places where that's hard or impossible and your regex code is a good example of that. I write a fair amount of C at the moment and you can have some pointer arithmetic that's not even that complicated, but a comment on it makes scanning through the function much simpler.
  - fishtoaster 4y ago
    > If you have a 4 line stanza that needs a comment to explain what it's doing then I'd suggest that needs breaking out into a function I'm mostly in agreement, so I'm going to focus on my disagreement too! ;) This view is pretty common in the ruby community. So much so that I think they take it too far at times. I sometimes find myself reading a class that could have been a single 24-line method but is instead one method with method calls, each of which calls 0-2 more methods. This style is good for when I'm trying to quickly understand what that class is supposed to do - I just read the top-level method that looks like: thing = getThing() munge { |i| thing[i] } is_foobar?(thing) But it's terrible when I need to understand what that function is actually doing - eg to debug it or to find some underlying function call I'm looking for. I have to bounce all over the file to mentally reconstruct a linear sequence of code which could have just been one function with some headers. Of course, this style is a reaction to impenetrable 500-line functions which are also terrible. I'd definitely prefer many small functions to that! I think it's a matter of judgement and experience to know whether some code is better as small stanzas with comments or small functions.
thomastjeffery 4y ago
The "why" is the most underrated aspect to good documentation. I generally prefer the word "context". The trickiest aspects of writing and editing software tend to boil down to two subjects: 1. What's the underlying system we are trying to manipulate? How is its data structured, and what kind of loops and logic branches can be hijacked for our new functionality? 2. Where and when is our new code interacting with the underlying structure? 3. To tie the first two together, what data/functionality are we exposing to the user? How and when? What is the user? Most contemporary programming over the last two decades has been focused on nouns. The last 5-10 years has seen a shift in popularity to verb-based (functional programming) paradigms. We can find insight from noun-based programming to answer "what?", and verb-based programming is good at answering, "how?". Neither really do a good job of answering "where?" or "why?". Those have to be peiced together like evidence in a crime scene, and by the time you figure it out, you've probably learned everything there is to know about the entire codebase.

fishtoaster 4y ago

I think "why" comments are the most useful, but "what" comments are a bit undervalued. A few types of "what" comments are, I find, very useful: 1. Comments that are effectively headers: # If the user is foobar, do thing user = User.find(current_user_id) user.preload_bizbaz!(cache: false) is_foobar = user.bizbaz.foobar.status == "yes" if (is_foobar) { do_thing(user) } Yes, you can read the 4 lines of code to see the "what' - the comment is duplicative. But when I'm skimming through a large codebase trying to find or understand something, these headers can be invaluable. 2. Comments on dense code # Matches any email like foo@bar.com (only .com, .net, .org email addresses) return email.match(/^.*@.*\.(com|net|org)$/) Yes I can that regex, but I can read that comment a lot faster.

vikingerik 4y ago
And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it.
- Arrath 4y ago
  Next up: comments that dynamically generate from the code itself, like tooltips in a game. /s "...only from %s domains..."
  - mr_toad 4y ago
    Like GPT in reverse? I wonder how long it will take before someone tries to use an AI to document code.
- tablespoon 4y ago
  > And the latter is a perfect example of what goes wrong, when someone adds "gov" to the regex but doesn't notice the comment to update it. That always gets trotted out, but it's sort of like "don't write code unless you can guarantee the code won't have any bugs, so never write any code." The trick is write code and comments, but be a little skeptical of both. If you're disciplined (especially with commit messages), it's usually pretty easy to figure out a mistake or omission after the fact.
coryrc 4y ago
Those are perfect examples of what not to do.
ezkhimo 4y ago
For your first example, use a method with a fitting name. Second one is not a good example, because I think it's a very common pattern and email.match with com|net|org provides enough context by itself. It's just bloat imo.
m000 4y ago
I love header comments, but many people fail to get their usefulness, and I get the "good code does not need comments" mantra recited to me pretty often. Here is the thing: Header comments are not really about explaining their following code. They are about reducing the lines you need to read to navigate through the code by a factor of 5 to 10. Huge time-saver, and helps a ton newcomers to become productive quickly.
raytracer 4y ago
I like header comments too, but I almost never use them when working on a team. I feel like there are a bunch of coding habits that work well for solo developers but not devs on a team.
tablespoon 4y ago
> I think "why" comments are the most useful, but "what" comments are a bit undervalued. A few types of "what" comments are, I find, very useful: I agree. However, "what" comments need a little more skill and judgement to know what to write and what to leave out. Having a terrible memory helps develop that skill, because you kind of get a sense of what you'll want explained to you again in six months and what's hard to decode.
amalcon 4y ago
My favorite type of "What" comment is: // The following block should have the same // result as this (simpler) code: // <code> // but for <reason> this version is better This is great for things like opaque optimizations, things that mimic a library function except for one critical difference, blocks that become really convoluted to deal with special cases, and similar.
osigurdson 4y ago
>> Yes I can that regex, but I can read that comment a lot faster. Regex is the worst language that everyone needs to know.
- Raidion 4y ago
  I like the joke "if you decide to use regex to solve a problem, you now have two problems"
MaurizioPz 4y ago
1. would be better as a function, so you have: - a nice explanatory name to it - if the functionality changes then it is more probable that the name would change - the code is hidden away if you don't care about the why (maybe you are looking for something else)
rkangel 4y ago
I am 99% in agreement with everything you said, so of course I'm going to focus on the 1%! If you have a 4 line stanza that needs a comment to explain what it's doing then I'd suggest that needs breaking out into a function so that your code then becomes `if (is_foobar?(current_user_id)) {do_thing()}`. Just as readable with no comments needed. There are definitely places where that's hard or impossible and your regex code is a good example of that. I write a fair amount of C at the moment and you can have some pointer arithmetic that's not even that complicated, but a comment on it makes scanning through the function much simpler.
- fishtoaster 4y ago
  > If you have a 4 line stanza that needs a comment to explain what it's doing then I'd suggest that needs breaking out into a function I'm mostly in agreement, so I'm going to focus on my disagreement too! ;) This view is pretty common in the ruby community. So much so that I think they take it too far at times. I sometimes find myself reading a class that could have been a single 24-line method but is instead one method with method calls, each of which calls 0-2 more methods. This style is good for when I'm trying to quickly understand what that class is supposed to do - I just read the top-level method that looks like: thing = getThing() munge { |i| thing[i] } is_foobar?(thing) But it's terrible when I need to understand what that function is actually doing - eg to debug it or to find some underlying function call I'm looking for. I have to bounce all over the file to mentally reconstruct a linear sequence of code which could have just been one function with some headers. Of course, this style is a reaction to impenetrable 500-line functions which are also terrible. I'd definitely prefer many small functions to that! I think it's a matter of judgement and experience to know whether some code is better as small stanzas with comments or small functions.

thomastjeffery 4y ago

The "why" is the most underrated aspect to good documentation. I generally prefer the word "context". The trickiest aspects of writing and editing software tend to boil down to two subjects: 1. What's the underlying system we are trying to manipulate? How is its data structured, and what kind of loops and logic branches can be hijacked for our new functionality? 2. Where and when is our new code interacting with the underlying structure? 3. To tie the first two together, what data/functionality are we exposing to the user? How and when? What is the user? Most contemporary programming over the last two decades has been focused on nouns. The last 5-10 years has seen a shift in popularity to verb-based (functional programming) paradigms. We can find insight from noun-based programming to answer "what?", and verb-based programming is good at answering, "how?". Neither really do a good job of answering "where?" or "why?". Those have to be peiced together like evidence in a crime scene, and by the time you figure it out, you've probably learned everything there is to know about the entire codebase.