4 ms·

I’ve hunted down contact info and emailed a dev who’d left the company to thank them for the clean code they left behind. I encountered their code while debugg

I’ve hunted down contact info and emailed a dev who’d left the company to thank them for the clean code they left behind. I encountered their code while debugging weird behavior in a legacy feature. The code structure was immediately intuitive and comprehensible. Just the right amount of detailed but not superfluous commenting. Beautiful. It made my day so I let them know!

wouldbecouldbe 3y ago
I never had code where I was like, oh this has too many comments. I never get this sentiment from developers. I've had reviews were developers wanted me to slim down & rewrite comments. It's often hard in the moment to understand what's obvious or not. Just always writing a comment even if it's obvious can save a lot of pain in the future.
- danbruc 3y ago
  You have never seen a comment that helpfully explains that getUsername() returns a string with the username of the user that the method is invoked on?
  - CodeyWhizzBang 3y ago
    Or the classic result of updating the code but not updating the comment: //Returns the user's full name return user.email;
    - andelink 3y ago
      Okay but when you see that why not just take 30 seconds and update the comment? Edit: if even 30 seconds
      - dack 3y ago
        in a collaborative environment, it's rarely 30 seconds to make such a change though. usually you have to make a commit with message, make a PR, submit the PR and get someone to review it (many orgs require code review for every change), then merge it. And each of those steps usually require you to context switch from whatever else you were actually trying to get done. Now, if you're already changing that part of the code/file, then sure it's pretty low overhead. But for something as simple as that function, I'd probably delete the comment entirely.
        andelink 3y ago
        For something as small as a code comment change, it's super fast, and honestly not worth the local branch stage -> commit -> push flow. Assuming GitHub, just edit it within the browser (if you find it in your editor, press the hotkey for opening the source in GitHub, if you're already in the browser, great). Make the change, hit commit (which defaults to a feature branch, you can change this), and then GitHub automatically opens up a PR template for your to then hit "create." Add reviewer(s), enable auto-merge, then forget about it.
        whstl 3y ago
        If something like that is generating a lot of bureaucracy and time-wasting, then there are several other pressing problems that are much worse than that. My company is heavily regulated (finance) and highly bureaucratic, but I still just merge those PRs without waiting for the CI or without even bothering clicking approve, I just look at it. When I find one myself I just merge to master or edit in Github directly. No auditor has ever batted an eye to that.
    - wouldbecouldbe 3y ago
      yeah that's an issue, but the much easier to update a comment then an extensive suite of unit tests. And in my experience the payoff of good comments is about the same, minus the cost.
  - wouldbecouldbe 3y ago
    I'd rather someone over does it then under does it. The issue is that most things are obvious when you write the code, but that it's often not clear what's not obvious in the future. So if you just get in the habit of explain every function it will lead to a more understandable codebase.
    - danbruc 3y ago
      Obvious is and will be what the code does, not obvious is and will be why the code does it. I hate when people write comments explaining what the code does, I can just read the code and I will know. Why write it twice and open the possibility for inconsistencies? Is the comment wrong - forgotten to be updated maybe - as the code does something different then the comment says or does the code have a bug and it should actually do what the comment says? Also if your code can not be easily understood, then improve the code instead of trying to explain it in comments. Good reasons for comments explaining what the code does are few and far between. On the other hand I want people to comment why they do what they do and why they do it the way they do it, that are things that are hard or impossible to infer from the code. Unfortunately, at least in my experience, people tend to write way to many what and way to few why comments.
  - whstl 3y ago
    I have seen plenty of it, but it doesn't bother me at all, especially with IDE syntax highlighting. The near-zero-documentation policy seen in some codebases bothers me 10x more.
  - KronisLV 3y ago
    > You have never seen a comment that helpfully explains that getUsername() returns a string with the username of the user that the method is invoked on? Yes, but that's not all that annoying when the opposite is you stumbling upon a service pattern with uncommented methods along the lines of CVKUser getCVKUser(int cvkId, ...) or VFUser getVFUser(int cktId, ...), without having any idea what the person writing the code 4 years ago was thinking. You've no idea what CVK or VF is supposed to be and have to spend an hour looking at both of those classes, as well as everything that surrounds them in the codebase, as well as what cvkId and cktId are supposed to be and why cktId supposedly matches VFUser, to do enough code archaeology, so you're able to figure things out confidently. That said, there is little use in code comments that explain WHAT the code does for trivial bits of code, instead of comments that explain WHY it works like that (like a more sane version of having to dig through Jira tickets, or years of commit history, or old pull requests, or whatever) or what other considerations there are to take into account (since separate docs won't be read as much and Jira tickets won't always have the technical information).
- endless1234 3y ago
  I've seen comments that basically amount to "here we set the variable to 5". Comments also come with a maintenance burden, it's easy to forget to update them when the code changes.
- dugmartin 3y ago
  The issue I’ve seen in older codebases is comments not being updated when the corresponding code updates. This usually is more of a problem for comments that are not local to the code, whether they are in docs or in a separate code file. Once enough of that creeps in you start distrusting comments and thus stop reading them.
- mattpallissard 3y ago
  > I never had code where I was like, oh this has too many comments. It happens. Even worse is when the code has been updated but the comments have not. I've picked up the habit of double checking comments with git blame.

wouldbecouldbe 3y ago

I never had code where I was like, oh this has too many comments. I never get this sentiment from developers. I've had reviews were developers wanted me to slim down & rewrite comments. It's often hard in the moment to understand what's obvious or not. Just always writing a comment even if it's obvious can save a lot of pain in the future.

danbruc 3y ago
You have never seen a comment that helpfully explains that getUsername() returns a string with the username of the user that the method is invoked on?
- CodeyWhizzBang 3y ago
  Or the classic result of updating the code but not updating the comment: //Returns the user's full name return user.email;
  - andelink 3y ago
    Okay but when you see that why not just take 30 seconds and update the comment? Edit: if even 30 seconds
    - dack 3y ago
      in a collaborative environment, it's rarely 30 seconds to make such a change though. usually you have to make a commit with message, make a PR, submit the PR and get someone to review it (many orgs require code review for every change), then merge it. And each of those steps usually require you to context switch from whatever else you were actually trying to get done. Now, if you're already changing that part of the code/file, then sure it's pretty low overhead. But for something as simple as that function, I'd probably delete the comment entirely.
      - andelink 3y ago
        For something as small as a code comment change, it's super fast, and honestly not worth the local branch stage -> commit -> push flow. Assuming GitHub, just edit it within the browser (if you find it in your editor, press the hotkey for opening the source in GitHub, if you're already in the browser, great). Make the change, hit commit (which defaults to a feature branch, you can change this), and then GitHub automatically opens up a PR template for your to then hit "create." Add reviewer(s), enable auto-merge, then forget about it.
      - whstl 3y ago
        If something like that is generating a lot of bureaucracy and time-wasting, then there are several other pressing problems that are much worse than that. My company is heavily regulated (finance) and highly bureaucratic, but I still just merge those PRs without waiting for the CI or without even bothering clicking approve, I just look at it. When I find one myself I just merge to master or edit in Github directly. No auditor has ever batted an eye to that.
  - wouldbecouldbe 3y ago
    yeah that's an issue, but the much easier to update a comment then an extensive suite of unit tests. And in my experience the payoff of good comments is about the same, minus the cost.
- wouldbecouldbe 3y ago
  I'd rather someone over does it then under does it. The issue is that most things are obvious when you write the code, but that it's often not clear what's not obvious in the future. So if you just get in the habit of explain every function it will lead to a more understandable codebase.
  - danbruc 3y ago
    Obvious is and will be what the code does, not obvious is and will be why the code does it. I hate when people write comments explaining what the code does, I can just read the code and I will know. Why write it twice and open the possibility for inconsistencies? Is the comment wrong - forgotten to be updated maybe - as the code does something different then the comment says or does the code have a bug and it should actually do what the comment says? Also if your code can not be easily understood, then improve the code instead of trying to explain it in comments. Good reasons for comments explaining what the code does are few and far between. On the other hand I want people to comment why they do what they do and why they do it the way they do it, that are things that are hard or impossible to infer from the code. Unfortunately, at least in my experience, people tend to write way to many what and way to few why comments.
- whstl 3y ago
  I have seen plenty of it, but it doesn't bother me at all, especially with IDE syntax highlighting. The near-zero-documentation policy seen in some codebases bothers me 10x more.
- KronisLV 3y ago
  > You have never seen a comment that helpfully explains that getUsername() returns a string with the username of the user that the method is invoked on? Yes, but that's not all that annoying when the opposite is you stumbling upon a service pattern with uncommented methods along the lines of CVKUser getCVKUser(int cvkId, ...) or VFUser getVFUser(int cktId, ...), without having any idea what the person writing the code 4 years ago was thinking. You've no idea what CVK or VF is supposed to be and have to spend an hour looking at both of those classes, as well as everything that surrounds them in the codebase, as well as what cvkId and cktId are supposed to be and why cktId supposedly matches VFUser, to do enough code archaeology, so you're able to figure things out confidently. That said, there is little use in code comments that explain WHAT the code does for trivial bits of code, instead of comments that explain WHY it works like that (like a more sane version of having to dig through Jira tickets, or years of commit history, or old pull requests, or whatever) or what other considerations there are to take into account (since separate docs won't be read as much and Jira tickets won't always have the technical information).
endless1234 3y ago
I've seen comments that basically amount to "here we set the variable to 5". Comments also come with a maintenance burden, it's easy to forget to update them when the code changes.
dugmartin 3y ago
The issue I’ve seen in older codebases is comments not being updated when the corresponding code updates. This usually is more of a problem for comments that are not local to the code, whether they are in docs or in a separate code file. Once enough of that creeps in you start distrusting comments and thus stop reading them.
mattpallissard 3y ago
> I never had code where I was like, oh this has too many comments. It happens. Even worse is when the code has been updated but the comments have not. I've picked up the habit of double checking comments with git blame.