10 ms·

Isn’t commented code no longer considered a good idea in most companies? I used to work for a bank and the policy is no comments unless absolutely necessary, b

Isn’t commented code no longer considered a good idea in most companies? I used to work for a bank and the policy is no comments unless absolutely necessary, because comments become out of date. Doxygen is the only real comments allowed.

almet 3y ago
I'm not sure the ratio of comments to LoC is a sign of good quality code. Too many comments might actually be a bad thing. It's more lines to maintain, and sometimes the comments just tell what the code is doing where there is no need to.
- brazzledazzle 3y ago
  I find that comments are most valuable when onboarding/understanding an unfamiliar code base. Comments composed of a little bit of “what” some “where” and a lot of “why” seems best for this scenario.
makeworld 3y ago
Wow, that seems strange to me. Seems like the policy should be to make comments when needed, and keep them up to date.
paxys 3y ago
That's an idiotic policy and definitely not something that is industry standard. Code gets out of date as well, so let's just stop writing it altogether..
- jacobsenscott 3y ago
  Even better, lets triple the work and require UML diagrams, comments, and code to all be in sync at all times!
  - dylan604 3y ago
    you left out keeping the docs in sync as well
  - chinchilla2020 3y ago
    don't forget the random google sheet that the project manager wants to keep updated
- ckdot2 3y ago
  If code is wrong or out of date, the program will fail or stop doing that it's supposed to do. If comments are wrong or out of date, it will mislead the developer or at least confuse them if the comment says something else than the code. A wrong comment is worse than no comment - and usually developers don't care about comments as much as for the code. Why comment some code anyway if the code is easy to read? The only reason is to explain -why- something has been developed, not -how-.
  - didntcheck 3y ago
    The identifier can become out of date. The common argument against comments is that they're an indicator that you should factor that block out into a function with a descriptive name, but I can say for certain that method names can easily become out of date. As for doing neither, well at the end of the day you probably do want a way to summarise a block of code to the next human, rather than requiring them to read every statement Actually, speaking as someone's who's been generally critical of the "get AI to write our PRs!" thing, having an AI attempt a quick sanity check of comments near where your edits are could maybe work well
- pasquinelli 3y ago
  the code can't get out of sync with itself. i agree, that's a dumb policy. boilerplate comments are just as bad as boilerplate code-- the policy should be to comment when something is notable, in the manner that's appropriate for the context. but comments telling you one thing is happening when something else is happening is a problem, and i suppose it couldn't happen if the comments weren't there.
flatline 3y ago
It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commented. Generally I’ve found uncommented code bases to be thrown together haphazardly and to be of lower quality. Same with those that only trivially leave comment breadcrumbs about what is being done, duplicating the code itself.
- bravetraveler 3y ago
  "Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish. I tend to treat them like a strange hybrid of a story with editor's notes. Here's where we're going... but oh no! Something is in the way. We need this critical, but painful to acquire shovel. If I anticipate even the slightest bit of refactoring around it, I'm noting what devilishness lead me down this path. TLDR: anything that could be abstracted away/not exist, probably deserves comments on why it does... perhaps even how it could be removed.
  - bsder 3y ago
    > "Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish. And "profanity" in code is almost by definition a "Why"-type comment. You don't get upset and leave a profane comment unless you did a deep dive and realized the code does something absurdly horrible that took you far too long to figure out.
    - Groxx 3y ago
      Yeah. It's deep-dive "oh God it's all terrible isn't it" discoveries, often containing some of the cursed knowledge that was obtained, not // this shit implements fizzbuzz fizzbuzz()
    - 3y ago
IshKebab 3y ago
No, that is stupid. People just don't want you to write comments like // Set foo to true foo = true; Somebody saw one too many comments like that and overreacted. As long as you a) don't write comments describing what is self evident from the code, and b) try to make the code as descriptive as possible, then it's fine. Comment away.
- ckdot2 3y ago
  it's not always as simple as that. what if you once implemented some facade method to get data from database like "findProductById" and you comment it with "finds a product from database by it's ID". later on, someone (maybe you) replaced some deeper logic here, so the product might be fetched from some other source, depending on some configuration. in case you didn't even touch the facade file, will you remember to update the comment? most developers will not. this risk is ALWAYS present if the comment explains more than the nearby code. so a comment is only safe if it contains the same degree of information like the nearby code. in that case though the comment is redundant. comments only make sense if they explain the -why-, not the -what- or -how-.
  - IshKebab 3y ago
    First of all you shouldn't comment "finds a product from database by it's ID" because that's just what the function name already says. Second, you're (I think) arguing that we shouldn't use comments because they might go out of date, which I think is throwing the baby out with the bath water. > comments only make sense if they explain the -why-, not the -what- or -how- That is the wrong heuristic. Comments make sense if they provide useful information that isn't self-evident from the code. Often that is the "why", but it can also be the "what" or the "how". Think about something like the fast inverse square root. A comment explaining how it works is very valuable.
    - gpderetta 3y ago
      Besides, even function names can go out of date, yet we still give functions meaningful names.
vezuchyy 3y ago
If you have a process where every commit is well documented, you don't need much comments since you can rely on whatever is your analogue for git blame. It's not a lack of comments, it's actually the opposite but aside from the code base. When I worked at SAP where VCS for ABAP is ancient and has no analogue for git blame we had a practice of putting a SAP Note next to every code change, since some of the things that we had to implement are dictated by business/legislation, so you need a proper explanation from time to time. Without it, the code becomes unmaintainable.
- ShadowBanThis01 3y ago
  That requires everyone to have access to the repo, and to wade through it looking for changes to the relevant area of code you're working in. That sucks.
  - tormeh 3y ago
    In which situation would you not have access to the repo? I guess if it's a library or something, but libraries must always be documented in a different way to business code.
    - ShadowBanThis01 3y ago
      Maybe you're a contractor. Maybe it's legacy code that has simply been archived. Maybe the network is down. Maybe there was a bad migration. Sidecars generally suck because they get lost.
      - cerved 3y ago
        If that's the case, you have bigger problems than documentation
        ShadowBanThis01 3y ago
        Like what?
smrtinsert 3y ago
I get where they are going with it - every block of code should probably be obvious and final since it has one item to do well. Unfortunately there are always times when n random fields will be used for a conditional that is completely non-obvious. Comments will always be necessary to some degree.
fx1994 3y ago
that's why three and I think the fourth will leave our company after original developer left undocumented and hard to understand code (it's pretty complex and has tons of hacks to work on different OS'es), first year they learn what the hell is that code, how it works and they are not allowed to comment anything (I asked few times why we waste so much time for basic stuff, they said it is unnecessary...ok I guess). Now they hired original developer for tons of money just to consult newest developer and explain him code. Reasonable I guess.
throwaway14356 3y ago
While I carefully keep others away from my code the notes say I have a complicated relationship with my future self. While comments should be the least useful to me I've tried many formats and found that it is spectacular to have the full elaborate comment above each bite sized nugget of code. I mean that what was solved as a single thing after breaking down the larger problem. The result is that I don't read any code at all. The whole thing is compiled to the native format that is human language. The code is great for illustration. If I keep it in separate files as documentation it takes to much effort to find and update. It takes needles extra effort and is less precise. It is just a personal preference of course but if one had any experience writing code in any language it should be easy to grasp say at 4 am while drunk.
furyofantares 3y ago
No-comments are better than low-effort, low-quality, unmaintained comments, for sure. You can imagine a world where all the projects that aren't realistically going to spend the effort on high-quality maintained comments makes the correct choice to skip comments unless absolutely necessary. And where projects that are realistically going to put effort into high-quality, maintained comments, do so. In this world, comment density would correlate highly with code quality per line of code. Profanity might not, I'm not sure. I do think you'd still find profanity in high-effort, high-quality, maintained comments, but it might indicate lower quality surrounding code, not higher. And it would still be unclear whether the existence of comments are a cause of higher quality code, or just a proxy for amount of effort and care taken per line of code.
hakunin 3y ago
Pasting again my 4 reasons to leave a code comment: 1. An odd business requirement (share the origin story) 2. It took research (summarize with links) 3. Multiple options were considered (justify decision) 4. Question in a code review (answer in a comment) And the article on how/what/why in code: https://max.engineer/maintainable-code https://max.engineer/maintainable-code
- ikekkdcjkfke 3y ago
  If the code doesn't speak for itself...
  - hakunin 3y ago
    …then I would suggest altering the code to speak for itself. If you can't do that any further, refer to the 4 reasons to leave a comment.
    - someweirdperson 3y ago
      And those meaningful relevant comments will be invisible in between those useless comments that were added to satisfy some tool that counts them.
- josephg 3y ago
  I’d also add: - The code is not self describing for some reason (eg duffs device, complex math, non obvious cases, etc) - The code is correct but it looks intuitively wrong. This comes up every few thousand lines for me, where some conditional looks redundant or twisted up for some reason - like maybe there’s weird choices to keep the borrow checker happy. I leave a note to myself because next time I read that code I’ll want to “fix” it. - Internal function preconditions / invariants. Eg, “this method must only be called while the XXX mutex is held” / “this code can only be reached when YYY is true because <reason>”. Sometimes these checks can be cheaply expressed in assertions, but not always. And sometimes you need comments as well to describe the nuances of what’s going on. Rereading my comment, maybe these are all examples of comments used to support code that’s not self describing. I’ve been programming for about 30 years now. I don’t think self describing code is always possible or desirable. I prefer fewer, longer functions with comments than digging through dozens of tiny functions spread everywhere. Large functions are usually easier to write and to read.
gen220 3y ago
If you're curious to read a well-earned take on comments: http://antirez.com/news/124 http://antirez.com/news/124. Inline comments are a reflection on the authors' abilities to write good comments. They can be kinda useless, actually-bad, or really helpful. One canonical example of a "good comment" is explaining why a strange or not-the-least-complex approach was taken to implementing a certain solution. The code is like chesterton's fence, and the comment is a post explaining why it's there. That way, future readers can better assess for themselves whether it's worth their time trying to tear down the fence.

almet 3y ago

I'm not sure the ratio of comments to LoC is a sign of good quality code. Too many comments might actually be a bad thing. It's more lines to maintain, and sometimes the comments just tell what the code is doing where there is no need to.

brazzledazzle 3y ago
I find that comments are most valuable when onboarding/understanding an unfamiliar code base. Comments composed of a little bit of “what” some “where” and a lot of “why” seems best for this scenario.

makeworld 3y ago

Wow, that seems strange to me. Seems like the policy should be to make comments when needed, and keep them up to date.

paxys 3y ago

That's an idiotic policy and definitely not something that is industry standard. Code gets out of date as well, so let's just stop writing it altogether..

jacobsenscott 3y ago
Even better, lets triple the work and require UML diagrams, comments, and code to all be in sync at all times!
- dylan604 3y ago
  you left out keeping the docs in sync as well
- chinchilla2020 3y ago
  don't forget the random google sheet that the project manager wants to keep updated
ckdot2 3y ago
If code is wrong or out of date, the program will fail or stop doing that it's supposed to do. If comments are wrong or out of date, it will mislead the developer or at least confuse them if the comment says something else than the code. A wrong comment is worse than no comment - and usually developers don't care about comments as much as for the code. Why comment some code anyway if the code is easy to read? The only reason is to explain -why- something has been developed, not -how-.
- didntcheck 3y ago
  The identifier can become out of date. The common argument against comments is that they're an indicator that you should factor that block out into a function with a descriptive name, but I can say for certain that method names can easily become out of date. As for doing neither, well at the end of the day you probably do want a way to summarise a block of code to the next human, rather than requiring them to read every statement Actually, speaking as someone's who's been generally critical of the "get AI to write our PRs!" thing, having an AI attempt a quick sanity check of comments near where your edits are could maybe work well
pasquinelli 3y ago
the code can't get out of sync with itself. i agree, that's a dumb policy. boilerplate comments are just as bad as boilerplate code-- the policy should be to comment when something is notable, in the manner that's appropriate for the context. but comments telling you one thing is happening when something else is happening is a problem, and i suppose it couldn't happen if the comments weren't there.

flatline 3y ago

It really depends on the comments. Best practice is to comment “why” something was done, not “what” is being done, or “how”. Every programmer can read code, most code should be pretty self-explanatory. But in any sufficiently complex routine, there are going to be some things that a programmer struggled to get working the first time, that they had to work around, or that was simply unintuitive. These should be commented. Generally I’ve found uncommented code bases to be thrown together haphazardly and to be of lower quality. Same with those that only trivially leave comment breadcrumbs about what is being done, duplicating the code itself.

bravetraveler 3y ago
"Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish. I tend to treat them like a strange hybrid of a story with editor's notes. Here's where we're going... but oh no! Something is in the way. We need this critical, but painful to acquire shovel. If I anticipate even the slightest bit of refactoring around it, I'm noting what devilishness lead me down this path. TLDR: anything that could be abstracted away/not exist, probably deserves comments on why it does... perhaps even how it could be removed.
- bsder 3y ago
  > "Why" is a really good way to put it, like you say - doing "What" just repeats something a novice, possibly even a layman, could distinguish. And "profanity" in code is almost by definition a "Why"-type comment. You don't get upset and leave a profane comment unless you did a deep dive and realized the code does something absurdly horrible that took you far too long to figure out.
  - Groxx 3y ago
    Yeah. It's deep-dive "oh God it's all terrible isn't it" discoveries, often containing some of the cursed knowledge that was obtained, not // this shit implements fizzbuzz fizzbuzz()
  - 3y ago

IshKebab 3y ago

No, that is stupid. People just don't want you to write comments like // Set foo to true foo = true; Somebody saw one too many comments like that and overreacted. As long as you a) don't write comments describing what is self evident from the code, and b) try to make the code as descriptive as possible, then it's fine. Comment away.

ckdot2 3y ago
it's not always as simple as that. what if you once implemented some facade method to get data from database like "findProductById" and you comment it with "finds a product from database by it's ID". later on, someone (maybe you) replaced some deeper logic here, so the product might be fetched from some other source, depending on some configuration. in case you didn't even touch the facade file, will you remember to update the comment? most developers will not. this risk is ALWAYS present if the comment explains more than the nearby code. so a comment is only safe if it contains the same degree of information like the nearby code. in that case though the comment is redundant. comments only make sense if they explain the -why-, not the -what- or -how-.
- IshKebab 3y ago
  First of all you shouldn't comment "finds a product from database by it's ID" because that's just what the function name already says. Second, you're (I think) arguing that we shouldn't use comments because they might go out of date, which I think is throwing the baby out with the bath water. > comments only make sense if they explain the -why-, not the -what- or -how- That is the wrong heuristic. Comments make sense if they provide useful information that isn't self-evident from the code. Often that is the "why", but it can also be the "what" or the "how". Think about something like the fast inverse square root. A comment explaining how it works is very valuable.
  - gpderetta 3y ago
    Besides, even function names can go out of date, yet we still give functions meaningful names.

vezuchyy 3y ago

If you have a process where every commit is well documented, you don't need much comments since you can rely on whatever is your analogue for git blame. It's not a lack of comments, it's actually the opposite but aside from the code base. When I worked at SAP where VCS for ABAP is ancient and has no analogue for git blame we had a practice of putting a SAP Note next to every code change, since some of the things that we had to implement are dictated by business/legislation, so you need a proper explanation from time to time. Without it, the code becomes unmaintainable.

ShadowBanThis01 3y ago
That requires everyone to have access to the repo, and to wade through it looking for changes to the relevant area of code you're working in. That sucks.
- tormeh 3y ago
  In which situation would you not have access to the repo? I guess if it's a library or something, but libraries must always be documented in a different way to business code.
  - ShadowBanThis01 3y ago
    Maybe you're a contractor. Maybe it's legacy code that has simply been archived. Maybe the network is down. Maybe there was a bad migration. Sidecars generally suck because they get lost.
    - cerved 3y ago
      If that's the case, you have bigger problems than documentation
      - ShadowBanThis01 3y ago
        Like what?

smrtinsert 3y ago

I get where they are going with it - every block of code should probably be obvious and final since it has one item to do well. Unfortunately there are always times when n random fields will be used for a conditional that is completely non-obvious. Comments will always be necessary to some degree.

fx1994 3y ago

that's why three and I think the fourth will leave our company after original developer left undocumented and hard to understand code (it's pretty complex and has tons of hacks to work on different OS'es), first year they learn what the hell is that code, how it works and they are not allowed to comment anything (I asked few times why we waste so much time for basic stuff, they said it is unnecessary...ok I guess). Now they hired original developer for tons of money just to consult newest developer and explain him code. Reasonable I guess.

throwaway14356 3y ago

While I carefully keep others away from my code the notes say I have a complicated relationship with my future self. While comments should be the least useful to me I've tried many formats and found that it is spectacular to have the full elaborate comment above each bite sized nugget of code. I mean that what was solved as a single thing after breaking down the larger problem. The result is that I don't read any code at all. The whole thing is compiled to the native format that is human language. The code is great for illustration. If I keep it in separate files as documentation it takes to much effort to find and update. It takes needles extra effort and is less precise. It is just a personal preference of course but if one had any experience writing code in any language it should be easy to grasp say at 4 am while drunk.

furyofantares 3y ago

No-comments are better than low-effort, low-quality, unmaintained comments, for sure. You can imagine a world where all the projects that aren't realistically going to spend the effort on high-quality maintained comments makes the correct choice to skip comments unless absolutely necessary. And where projects that are realistically going to put effort into high-quality, maintained comments, do so. In this world, comment density would correlate highly with code quality per line of code. Profanity might not, I'm not sure. I do think you'd still find profanity in high-effort, high-quality, maintained comments, but it might indicate lower quality surrounding code, not higher. And it would still be unclear whether the existence of comments are a cause of higher quality code, or just a proxy for amount of effort and care taken per line of code.

hakunin 3y ago

Pasting again my 4 reasons to leave a code comment: 1. An odd business requirement (share the origin story) 2. It took research (summarize with links) 3. Multiple options were considered (justify decision) 4. Question in a code review (answer in a comment) And the article on how/what/why in code: https://max.engineer/maintainable-code https://max.engineer/maintainable-code

ikekkdcjkfke 3y ago
If the code doesn't speak for itself...
- hakunin 3y ago
  …then I would suggest altering the code to speak for itself. If you can't do that any further, refer to the 4 reasons to leave a comment.
  - someweirdperson 3y ago
    And those meaningful relevant comments will be invisible in between those useless comments that were added to satisfy some tool that counts them.
josephg 3y ago
I’d also add: - The code is not self describing for some reason (eg duffs device, complex math, non obvious cases, etc) - The code is correct but it looks intuitively wrong. This comes up every few thousand lines for me, where some conditional looks redundant or twisted up for some reason - like maybe there’s weird choices to keep the borrow checker happy. I leave a note to myself because next time I read that code I’ll want to “fix” it. - Internal function preconditions / invariants. Eg, “this method must only be called while the XXX mutex is held” / “this code can only be reached when YYY is true because <reason>”. Sometimes these checks can be cheaply expressed in assertions, but not always. And sometimes you need comments as well to describe the nuances of what’s going on. Rereading my comment, maybe these are all examples of comments used to support code that’s not self describing. I’ve been programming for about 30 years now. I don’t think self describing code is always possible or desirable. I prefer fewer, longer functions with comments than digging through dozens of tiny functions spread everywhere. Large functions are usually easier to write and to read.

gen220 3y ago

If you're curious to read a well-earned take on comments: http://antirez.com/news/124 http://antirez.com/news/124. Inline comments are a reflection on the authors' abilities to write good comments. They can be kinda useless, actually-bad, or really helpful. One canonical example of a "good comment" is explaining why a strange or not-the-least-complex approach was taken to implementing a certain solution. The code is like chesterton's fence, and the comment is a post explaining why it's there. That way, future readers can better assess for themselves whether it's worth their time trying to tear down the fence.