4 ms·

Those comments won't match the code in 6 months. Edit to add: and in 6 months, instead of being one short page of code, it'll be 600 lines long and impossible

Those comments won't match the code in 6 months. Edit to add: and in 6 months, instead of being one short page of code, it'll be 600 lines long and impossible to understand or modify safely

Supermancho 3y ago
Do other people not consider comments in PRs anymore? Would someone ok a PR [for a function] with 600 lines? Probably not. Let's not be absurd here, but I fundamentally agree that it's too long already. Yes, maybe it's the wrong abstraction or it won't match in 6 months because people will start calling Hats Pizzas and the logic will be different. Maybe I'll be dead tomorrow. I don't concern myself with what-ifs over unknowns. I want correctness and some assurance of it. I don't think writing 50? tests to cover this thing is a good way to spend my time (or someone else's). I'll write the left hand side first. When I'm looking at writing tests, it will become something like the right hand side. Yes linear code is more readable. That's something to consider, but it's not my primary consideration.
- MathMonkeyMan 3y ago
  Each PR has 20 lines, and there are 30 such PRs over six months.
  - Supermancho 3y ago
    Apologies. I wasn't clear. I meant it's a stretch to approve a function that's 600 lines. It would be very hard to reason about. I have clarified in my original post. Thank you for the feedback +1 to you.
    - readthenotes1 3y ago
      600 lines is relatively short for some of the bad code that I have seen...
- deleted 3y ago
  [deleted]
- bluGill 3y ago
  My code revivew tool shows me 3 lines of context around changes, which means the untouched comment won't even be seen unless i think to look for context. The tool also makes it hard to comment on those lines that were not touched but should have been. I've used many code review tools, all suffered from that. (the only exception wasn't a tool: print out of all the code to physical paper and then we all went into a meeting room to review for several hours - this was the best type of code review for finding things wrong, but it was also extremely expensive so I've only done that once in my life)
temple_os 3y ago
It's so ridiculous though! We have to get rid of comments because some random in the future might commit some rubbish? It's their fault! not mine! I'm just documenting what works at the time of publication
- readthenotes1 3y ago
  Hahaha! You are putting something in there that turns out to be disinformation. I used to believe as you did, but then I started actually looking at old code. I stored many examples, but I'll give you one to indicate just how bad most comments are: //Add 1 to x x:=x+2; Now why the original author thought it was important to explain in English what the next line of code was going to do in the programming language I am not sure. I am sure that someone figured out that it was a mistake and did the least they could possibly do to fix the mistake. Something like 80% or more of the comments I've seen have been misleading, wrong, or useless. If you do your own survey of someone else's old code so that your ego doesn't get in the way you will probably find something similar. Although I did talk with people working at NASA and they had someone on their code reviews who was specifically looking at comments. If you are that disciplined then your code will not be that bad, probably.
Mizoguchi 3y ago
Comments are meant to pass information to readers about rare cases that may not make much sense at first but have a reason to be. This is to avoid the introduction of bugs by tempting someone to refactor or "fix" your code. A properly written code, with good naming conventions for parameters, variables and functions should be easy to understand without comments. I should not need anyone to tell me the next few lines will //Heat oven That should be self explanatory by just looking at the code itself.

Those comments won't match the code in 6 months. Edit to add: and in 6 months, instead of being one short page of code, it'll be 600 lines long and impossible to understand or modify safely

Supermancho 3y ago

Do other people not consider comments in PRs anymore? Would someone ok a PR [for a function] with 600 lines? Probably not. Let's not be absurd here, but I fundamentally agree that it's too long already. Yes, maybe it's the wrong abstraction or it won't match in 6 months because people will start calling Hats Pizzas and the logic will be different. Maybe I'll be dead tomorrow. I don't concern myself with what-ifs over unknowns. I want correctness and some assurance of it. I don't think writing 50? tests to cover this thing is a good way to spend my time (or someone else's). I'll write the left hand side first. When I'm looking at writing tests, it will become something like the right hand side. Yes linear code is more readable. That's something to consider, but it's not my primary consideration.

MathMonkeyMan 3y ago
Each PR has 20 lines, and there are 30 such PRs over six months.
- Supermancho 3y ago
  Apologies. I wasn't clear. I meant it's a stretch to approve a function that's 600 lines. It would be very hard to reason about. I have clarified in my original post. Thank you for the feedback +1 to you.
  - readthenotes1 3y ago
    600 lines is relatively short for some of the bad code that I have seen...
deleted 3y ago
[deleted]
bluGill 3y ago
My code revivew tool shows me 3 lines of context around changes, which means the untouched comment won't even be seen unless i think to look for context. The tool also makes it hard to comment on those lines that were not touched but should have been. I've used many code review tools, all suffered from that. (the only exception wasn't a tool: print out of all the code to physical paper and then we all went into a meeting room to review for several hours - this was the best type of code review for finding things wrong, but it was also extremely expensive so I've only done that once in my life)

temple_os 3y ago

It's so ridiculous though! We have to get rid of comments because some random in the future might commit some rubbish? It's their fault! not mine! I'm just documenting what works at the time of publication

readthenotes1 3y ago
Hahaha! You are putting something in there that turns out to be disinformation. I used to believe as you did, but then I started actually looking at old code. I stored many examples, but I'll give you one to indicate just how bad most comments are: //Add 1 to x x:=x+2; Now why the original author thought it was important to explain in English what the next line of code was going to do in the programming language I am not sure. I am sure that someone figured out that it was a mistake and did the least they could possibly do to fix the mistake. Something like 80% or more of the comments I've seen have been misleading, wrong, or useless. If you do your own survey of someone else's old code so that your ego doesn't get in the way you will probably find something similar. Although I did talk with people working at NASA and they had someone on their code reviews who was specifically looking at comments. If you are that disciplined then your code will not be that bad, probably.

Mizoguchi 3y ago

Comments are meant to pass information to readers about rare cases that may not make much sense at first but have a reason to be. This is to avoid the introduction of bugs by tempting someone to refactor or "fix" your code. A properly written code, with good naming conventions for parameters, variables and functions should be easy to understand without comments. I should not need anyone to tell me the next few lines will //Heat oven That should be self explanatory by just looking at the code itself.