6 ms·

Might I recommend writing those weird business requirements down as comments instead of just hoping someone will guess them six months down the line?

mnsc 2y ago
So even if comments are flawlessly updated they are not a silver bullet. Not everyone are good at explaining confusing concepts in plain English so worst case you have confusing code and a comment that is 90% accurate but describe one detail in a way that doesn't really match what the code says. This will make you question if you have understood what the code does and it will take time and effort to convince yourself that code is in fact deterministic and unsurprising. (but most often the comment is is just not updated or updated along with the code but without full understanding, which is what caused the bug that is the reason you are looking at the code in question)
- rtpg 2y ago
  An outdated comment is still a datapoint! Including if the comment was wrong when it was first written! We live in a world with version history, repositories with change requests, communications… code comments are a part of that ecosystem. A comment that is outright incorrect at inception is still valuable even if it is at least an attempt by the writer to describe their internal understanding of things.
  - more-coffee 2y ago
    This. I have argued with plenty of developers on why comments are useful, and the counter arguments are always the same. I believe it boils down to a lack of foresight. At some point in time, someone is going to revisit your code, and even just a small `// Sorry this is awful, we have to X but this was difficult because of Y` will go a long way. While I (try to) have very fluid opinions in all aspects of programming, the usefulness of comments is not something I (think!) I'll ever budge on. :)
    - temporallobe 2y ago
      > // Sorry this is awful, we have to X but this was difficult because of Y You don’t know how many times I’ve seen this with a cute little GitLens inline message of “Brian Smith, 10 years ago”. If Brian couldn’t figure it out 10 years ago, I’m not likely going to attempt it either, especially if it has been working for 10 years.
      - larsrc 2y ago
        But knowing what Brian was considering at the time is useful, both due avoiding redoing that and for realising that some constraints may have been lifted.
  - xnx 2y ago
    We should call them code clues
  - temporallobe 2y ago
    It just occurred to me that perhaps this is where AI might prove useful. Functions could have some kind of annotation that triggers AI to analyze the function and explain it plain language when you do something like hover over the function name in the IDE, or, you can have a prompt where you can interact with that piece of code and ask it questions. Obviously this would mean developer-written comments would be less likely to make it into the commit history, but it might be better than nothing, especially in older codebases where the original developer(s) are long gone. Maybe this already exists, but I’m too lazy to research that right now.
    - bccdee 2y ago
      But then could you trust it not to hallucinate functionality that doesn't exist? Seems as risky as out-of-date comments, if not more What I'd really like is an AI linter than noticed if you've changed some functionality referenced in a comment without updating that comment. Then, the worst-case scenario is that it doesn't notice, and we're back where we started.
  - buttercraft 2y ago
    What if you don't know that the comment is wrong?
    - lexicality 2y ago
      IMO the only thing you can assume is that the person who wrote the comment wasn't actively trying to deceive you. You should treat all documentation, comments, function names, commit messages etc with a healthy dose of scepticism because no one truly has a strong grip on reality.
    - rtpg 2y ago
      Right, unlike code (which does what it does, even if that isn't what the writer meant) there's no real feedback loop for comments. Still worth internalizing the info based on that IMO. "This does X" as a comment when it in fact does Y in condition Z means that the probability you are looking at a bug goes up a bit! Without the comment you might not be able to identify that Y is not intentional. Maybe Y is intentional! In which case the comment that "this is intentional" is helpful. Perhaps the intentionality is also incorrect, and that's yet another data point! Fairly rare for there to be negative value in comments.
- michaelcampbell 2y ago
  > So even if comments are flawlessly updated they are not a silver bullet. This "has to be perfect in perpetuity or it is of no value" mentality I don't find helpful. Be kind to FutureDev. Comment the weird "why"s. If you need to change it later, adjust the comment.
  - bccdee 2y ago
    Yeah: "what if this code becomes tech debt later" applies to everything, not just comments. It's a tradeoff. The best thing you can do to avoid creating debt for later maintainers is to write code that's easy to delete, and adding comments helps with that.
  - mnsc 2y ago
    I don't think comments need to be perfect to have value. My point was that if a certain piece of code is solving a particularly confusing problem in the domain, explaining it in a comment doesn't _necessarily_ mean the code will be less confusing to future dev if the current developer is not able to capture the issue in plain English. Future dev would be happier I think with putting more effort into refactoring and making the code more readable and clear. When that fails, a "here be dragons" comment is valuable.
    - MichaelZuo 2y ago
      They can write a very long comment explaining why it is confusing them in X, Y, Z vague ways. Or even multilingual comments if they have better writing skills in another lanaguage. And even if they don’t know themselves why they are confused, they can still describe how they are confused.
      - deleted 2y ago
        [deleted]
      - stouset 2y ago
        And any attempt whatsoever is some improvement over doing nothing and wishing luck to the next guy.
- Zondartul 2y ago
  Comments that explain the intent, rather than implementation, are the more useful kind. And when intent doesn't match the actual code, that's a good hint - it might be why the code doesn't work.
- hedora 2y ago
  If a developer can’t write intelligible comments or straightforward code, then I’d argue they should find another job.
  - pixl97 2y ago
    I mean it's easy to say silly things like this, but in reality most developers suck in one way or another. In addition companies don't seem to give a shit about straightforward code, they want LOC per day and the cheapest price possible which leads to tons of crap code.
    - hallway_monitor 2y ago
      Each person has their own strengths, but a worthwhile team member should be able to meet minimum requirements of readability and comments. This can be enforced through team agreements and peer review. Your second point is really the crux of business in a lot of ways. The balance of quality versus quantity. Cost versus value. Long-term versus short term gains. I’m sure there are situations where ruthlessly prioritizing short term profit through low cost code is indeed the optimal solution. For those of us who love to craft high-quality code, the trick is finding the companies where it is understood and agreed that long-term value from high-quality code is worth the upfront investment and, more importantly, where they have the cash to make that investment.
      - pixl97 2y ago
        >I’m sure there are situations where ruthlessly prioritizing short term profit through low cost code is indeed the optimal solution This is mostly how large publicly traded corps work, unless they are ran by programmers that want great applications or are required by law, they tend to write a lot of crap.
    - mlloyd 2y ago
      >In addition companies don't seem to give a shit about straightforward code, they want LOC per day and the cheapest price possible which leads to tons of crap code. Companies don't care about LOC, they care about solving problems. 30 LOC or 30k LOC doesn't matter much MOST of the time. They're just after a solution that puts the problem to rest.
ozim 2y ago
Then in 3 months someone in between came changing the code slightly that makes comment obsolete but doesn’t update the comment. Making all worse not better. Issue trackers are much better because then in git you can find tickets attached to the change. No ticket explaining why - no code change. Why not in repo? because business people write tickets not devs. Then tickets are passed to QA who also does read the code but also need that information.
- jounker 2y ago
  Why did the reviewer approve the change if the developer didn’t update the comment? It sounds like people are failing at their jobs.
  - ozim 2y ago
    Oh that is one of my pet peeves. "If only people would do their jobs properly". So we just fire all the employees and hire better ones only because someone did not pay attention to the comment. Of course it is an exaggeration - but also in the same line people who think "others are failing at their jobs" - should pick up and do all the work there is to be done and see how long they go until they miss something or make a mistake. Solution should be systematic to prevent people from failing and not expecting "someone doing their job properly". Not having comments as something that needs a review reduces workload on everyone involved. Besides, interfaces for PRs they clearly mark what changed - they don't point what hasn't been changed. So naturally people review what has changed. You still get the context of course and can see couple lines above and below... But still I blame the tool not people.
larodi 2y ago
Business requirements deviate from code almost immediately. Serving several clients with customisation adds even more strain on the process. Eventually you want to map paragraphs of business req to code which is not a 1:1 mapping. Aging codebase and the ongoing operations make it even harder to maintain consistently. eventually people surrender.
K0nserv 2y ago
Comments are decent but flawed. Being a type proponent I think the best strategy is lifting business requirements into the type system, encoding the invariants in a way that the compiler can check.
- larsrc 2y ago
  Comments should describe what the type system can't. Connect, pitfalls, workarounds for bugs in other code, etc.
ajuc 2y ago
Requirements should be in the JIRA. JIRA number should be in the commit message. You do git blame and you see why each line is what it is. Comments are nice too, but they tend to lie the older they are. Git blame never lies.
- SleepyMyroslav 2y ago
  A code tends to be reused. When it happens jira is not likely to travel alongside the code. All 'older' jira tickets are useless broken links. All you have in practice is jira name. It usually happen with 'internal documentation' links as well. Git blame often lies when big merge was squashed. I mostly had these in Perforce so I might be wrong. Also when code travels between source version control servers and different source version control software it also loses information. I would say in my gamedev practical experience the best comments I saw are TODO implement me and (unit) test code that still runs. First clearly states that you have reached outside of what was planned before and 2nd allows you to inspect what code meant to do.
  - jounker 2y ago
    One of my favorite conventions is ‘TODO(username): some comment’. This lets attribution survive merges and commits and lets you search for all of someone’s comments using a grep.
    - ben_w 2y ago
      I tend to do: // TODO: <the name of some ticket>: <what needs to happen here> e.g. // TODO: IOS-42: Vogon construction fleet will need names to be added to this poetry reading room struct I've not felt my name is all that important for a TODO, as the ticket itself may be taken up by someone else… AFAICT they never have been, but they could have been.
- TeMPOraL 2y ago
  Jira entries get wiped arbitrarily. Git blame may not lie, but it doesn't survive larger organizational "refactoring" around team or company mergers. Or refactoring code out into separate project/library. Hell, often enough it doesn't survive commits that rename bunch of files and move other stuff around.

mnsc 2y ago

So even if comments are flawlessly updated they are not a silver bullet. Not everyone are good at explaining confusing concepts in plain English so worst case you have confusing code and a comment that is 90% accurate but describe one detail in a way that doesn't really match what the code says. This will make you question if you have understood what the code does and it will take time and effort to convince yourself that code is in fact deterministic and unsurprising. (but most often the comment is is just not updated or updated along with the code but without full understanding, which is what caused the bug that is the reason you are looking at the code in question)

rtpg 2y ago
An outdated comment is still a datapoint! Including if the comment was wrong when it was first written! We live in a world with version history, repositories with change requests, communications… code comments are a part of that ecosystem. A comment that is outright incorrect at inception is still valuable even if it is at least an attempt by the writer to describe their internal understanding of things.
- more-coffee 2y ago
  This. I have argued with plenty of developers on why comments are useful, and the counter arguments are always the same. I believe it boils down to a lack of foresight. At some point in time, someone is going to revisit your code, and even just a small `// Sorry this is awful, we have to X but this was difficult because of Y` will go a long way. While I (try to) have very fluid opinions in all aspects of programming, the usefulness of comments is not something I (think!) I'll ever budge on. :)
  - temporallobe 2y ago
    > // Sorry this is awful, we have to X but this was difficult because of Y You don’t know how many times I’ve seen this with a cute little GitLens inline message of “Brian Smith, 10 years ago”. If Brian couldn’t figure it out 10 years ago, I’m not likely going to attempt it either, especially if it has been working for 10 years.
    - larsrc 2y ago
      But knowing what Brian was considering at the time is useful, both due avoiding redoing that and for realising that some constraints may have been lifted.
- xnx 2y ago
  We should call them code clues
- temporallobe 2y ago
  It just occurred to me that perhaps this is where AI might prove useful. Functions could have some kind of annotation that triggers AI to analyze the function and explain it plain language when you do something like hover over the function name in the IDE, or, you can have a prompt where you can interact with that piece of code and ask it questions. Obviously this would mean developer-written comments would be less likely to make it into the commit history, but it might be better than nothing, especially in older codebases where the original developer(s) are long gone. Maybe this already exists, but I’m too lazy to research that right now.
  - bccdee 2y ago
    But then could you trust it not to hallucinate functionality that doesn't exist? Seems as risky as out-of-date comments, if not more What I'd really like is an AI linter than noticed if you've changed some functionality referenced in a comment without updating that comment. Then, the worst-case scenario is that it doesn't notice, and we're back where we started.
- buttercraft 2y ago
  What if you don't know that the comment is wrong?
  - lexicality 2y ago
    IMO the only thing you can assume is that the person who wrote the comment wasn't actively trying to deceive you. You should treat all documentation, comments, function names, commit messages etc with a healthy dose of scepticism because no one truly has a strong grip on reality.
  - rtpg 2y ago
    Right, unlike code (which does what it does, even if that isn't what the writer meant) there's no real feedback loop for comments. Still worth internalizing the info based on that IMO. "This does X" as a comment when it in fact does Y in condition Z means that the probability you are looking at a bug goes up a bit! Without the comment you might not be able to identify that Y is not intentional. Maybe Y is intentional! In which case the comment that "this is intentional" is helpful. Perhaps the intentionality is also incorrect, and that's yet another data point! Fairly rare for there to be negative value in comments.
michaelcampbell 2y ago
> So even if comments are flawlessly updated they are not a silver bullet. This "has to be perfect in perpetuity or it is of no value" mentality I don't find helpful. Be kind to FutureDev. Comment the weird "why"s. If you need to change it later, adjust the comment.
- bccdee 2y ago
  Yeah: "what if this code becomes tech debt later" applies to everything, not just comments. It's a tradeoff. The best thing you can do to avoid creating debt for later maintainers is to write code that's easy to delete, and adding comments helps with that.
- mnsc 2y ago
  I don't think comments need to be perfect to have value. My point was that if a certain piece of code is solving a particularly confusing problem in the domain, explaining it in a comment doesn't _necessarily_ mean the code will be less confusing to future dev if the current developer is not able to capture the issue in plain English. Future dev would be happier I think with putting more effort into refactoring and making the code more readable and clear. When that fails, a "here be dragons" comment is valuable.
  - MichaelZuo 2y ago
    They can write a very long comment explaining why it is confusing them in X, Y, Z vague ways. Or even multilingual comments if they have better writing skills in another lanaguage. And even if they don’t know themselves why they are confused, they can still describe how they are confused.
    - deleted 2y ago
      [deleted]
    - stouset 2y ago
      And any attempt whatsoever is some improvement over doing nothing and wishing luck to the next guy.
Zondartul 2y ago
Comments that explain the intent, rather than implementation, are the more useful kind. And when intent doesn't match the actual code, that's a good hint - it might be why the code doesn't work.
hedora 2y ago
If a developer can’t write intelligible comments or straightforward code, then I’d argue they should find another job.
- pixl97 2y ago
  I mean it's easy to say silly things like this, but in reality most developers suck in one way or another. In addition companies don't seem to give a shit about straightforward code, they want LOC per day and the cheapest price possible which leads to tons of crap code.
  - hallway_monitor 2y ago
    Each person has their own strengths, but a worthwhile team member should be able to meet minimum requirements of readability and comments. This can be enforced through team agreements and peer review. Your second point is really the crux of business in a lot of ways. The balance of quality versus quantity. Cost versus value. Long-term versus short term gains. I’m sure there are situations where ruthlessly prioritizing short term profit through low cost code is indeed the optimal solution. For those of us who love to craft high-quality code, the trick is finding the companies where it is understood and agreed that long-term value from high-quality code is worth the upfront investment and, more importantly, where they have the cash to make that investment.
    - pixl97 2y ago
      >I’m sure there are situations where ruthlessly prioritizing short term profit through low cost code is indeed the optimal solution This is mostly how large publicly traded corps work, unless they are ran by programmers that want great applications or are required by law, they tend to write a lot of crap.
  - mlloyd 2y ago
    >In addition companies don't seem to give a shit about straightforward code, they want LOC per day and the cheapest price possible which leads to tons of crap code. Companies don't care about LOC, they care about solving problems. 30 LOC or 30k LOC doesn't matter much MOST of the time. They're just after a solution that puts the problem to rest.

ozim 2y ago

Then in 3 months someone in between came changing the code slightly that makes comment obsolete but doesn’t update the comment. Making all worse not better. Issue trackers are much better because then in git you can find tickets attached to the change. No ticket explaining why - no code change. Why not in repo? because business people write tickets not devs. Then tickets are passed to QA who also does read the code but also need that information.

jounker 2y ago
Why did the reviewer approve the change if the developer didn’t update the comment? It sounds like people are failing at their jobs.
- ozim 2y ago
  Oh that is one of my pet peeves. "If only people would do their jobs properly". So we just fire all the employees and hire better ones only because someone did not pay attention to the comment. Of course it is an exaggeration - but also in the same line people who think "others are failing at their jobs" - should pick up and do all the work there is to be done and see how long they go until they miss something or make a mistake. Solution should be systematic to prevent people from failing and not expecting "someone doing their job properly". Not having comments as something that needs a review reduces workload on everyone involved. Besides, interfaces for PRs they clearly mark what changed - they don't point what hasn't been changed. So naturally people review what has changed. You still get the context of course and can see couple lines above and below... But still I blame the tool not people.

larodi 2y ago

Business requirements deviate from code almost immediately. Serving several clients with customisation adds even more strain on the process. Eventually you want to map paragraphs of business req to code which is not a 1:1 mapping. Aging codebase and the ongoing operations make it even harder to maintain consistently. eventually people surrender.

K0nserv 2y ago

Comments are decent but flawed. Being a type proponent I think the best strategy is lifting business requirements into the type system, encoding the invariants in a way that the compiler can check.

larsrc 2y ago
Comments should describe what the type system can't. Connect, pitfalls, workarounds for bugs in other code, etc.

ajuc 2y ago

Requirements should be in the JIRA. JIRA number should be in the commit message. You do git blame and you see why each line is what it is. Comments are nice too, but they tend to lie the older they are. Git blame never lies.

SleepyMyroslav 2y ago
A code tends to be reused. When it happens jira is not likely to travel alongside the code. All 'older' jira tickets are useless broken links. All you have in practice is jira name. It usually happen with 'internal documentation' links as well. Git blame often lies when big merge was squashed. I mostly had these in Perforce so I might be wrong. Also when code travels between source version control servers and different source version control software it also loses information. I would say in my gamedev practical experience the best comments I saw are TODO implement me and (unit) test code that still runs. First clearly states that you have reached outside of what was planned before and 2nd allows you to inspect what code meant to do.
- jounker 2y ago
  One of my favorite conventions is ‘TODO(username): some comment’. This lets attribution survive merges and commits and lets you search for all of someone’s comments using a grep.
  - ben_w 2y ago
    I tend to do: // TODO: <the name of some ticket>: <what needs to happen here> e.g. // TODO: IOS-42: Vogon construction fleet will need names to be added to this poetry reading room struct I've not felt my name is all that important for a TODO, as the ticket itself may be taken up by someone else… AFAICT they never have been, but they could have been.
TeMPOraL 2y ago
Jira entries get wiped arbitrarily. Git blame may not lie, but it doesn't survive larger organizational "refactoring" around team or company mergers. Or refactoring code out into separate project/library. Hell, often enough it doesn't survive commits that rename bunch of files and move other stuff around.