3 ms·

Smart developers don’t write mazes. > In code, comments are our signposts No. Naming and good architecture are. Intuitive folder trees. Concise docs. Clear se

by jorisw 11d ago

Smart developers don’t write mazes. > In code, comments are our signposts No. Naming and good architecture are. Intuitive folder trees. Concise docs. Clear separation of concerns such that naming can suffice. The more comments you need to ‘map’ your code, the worse of a job you’ve done.

pyrale 11d ago
> Smart developers don’t write mazes. You don’t choose what your forebears have written, though.
- jorisw 11d ago
  Patching that up by using comments as a 'map' isn't the right way to deal with that. Refactors and rearchitecture are. Putting in comments just helps procrastinate what's necessary.
  - stingraycharles 11d ago
    Rewrites require a lot of effort, significantly more than just adding comments. It’s a pragmatic tool until you actually have the time to do the rewrite.
    - jorisw 11d ago
      I never said rewrites. And the more you put in procrastination-encouraging half-solutions, the worse your code base gets.
  - adrianN 11d ago
    It's difficult to refactor and rearchitect without first understanding what's there and why.
    - jorisw 11d ago
      And yourself putting in comments is the solution to that?
      - adrianN 11d ago
        It depends on how much time you can spend on the task. If you're allowed to write proper documentation about architecture and requirements that is probably better. If you're just drive-by fixing the code, then good comments are a lot better than nothing.
  - pyrale 11d ago
    > Patching that up by using comments as a 'map' isn't the right way to deal with that. There is no right way. Only grey ones that help relieve pain for the team. > Refactors and rearchitecture are. Yeah... if you have the cash and the people. Usually, mature codebases are driven by limited investment with proven business value, because the sweet VC money is no longer there (or never was, in some industries). If you don't, reachitecturing is vanishingly rare, and your refactor budget is limited and you spend it carefully. If a piece of code hasn't moved recently but still comes up frequently when onboarding newcomers, documenting the code may be more profitable and less risky than changing it. It also helps preparing a case for a potential refactor.
- misswaterfairy 11d ago
  Though the onus is on us to improve what our forebears wrote, for the sake of our own and others' future.
  - pyrale 11d ago
    I agree with that. I'm just not sure all of us have the same leeway to improve the codebase, and the cost isn't the same either. When you have less means, you spend them more sparingly.
Tade0 11d ago
I'm afraid this all gets thrown out the window nowadays. Unless I tell them not to, LLMs lean on slapping verbose comments of the worst kind - describing the code instead of the reasons for putting it there. I ask them to write comments in ASD-STE100 Simplified Technical English, but all I really get from that is tersness. Also the other day I stumbled upon a huge pile of documentation and I'm still trying to figure out if it's human or machine written. I stopped reading it half way through as I figured that perhaps it wasn't written for humans to read.
- rootlocus 11d ago
  The most WTF comments are the ones that describe how the code looked during a rewrite session with no commits. It writes bad code, I ask it to rewrite it, and it leaves a comment saying why the previous implementation was bad, with no history in git of the previous implementation. Edit: changed the LLMs pronoun to it.
  - kuschku 11d ago
    Who is this "he" you're talking about? Or were you referring to an LLM? If so, the correct pronoun would be "it". Your english is really good, except for that little mistake.
    - rootlocus 11d ago
      I am 100% guitly of anthropomorphizing LLMs, sorry.
  - stakhanov 11d ago
    LLMs do this to communicate with their future selves to avoid retracing what turned out to be the garden path. Another pattern is where they put comments in multiple places in the code to say that those need to be kept in sync in a very particular way ...that sort of thing has always been considered a code smell, but seems to be the post-AI "new normal": it's cheaper for the AI to leave it to its future self to have to make every change in multiple places than it is for its present-day self to do the refactor. Before AI, writing code that worked was costly and structuring it well, while you were at it, didn't increase your cost all that much. Now, AI has reduced the cost of writing badly-structured but working code, while it hasn't reduced the cost of writing well-structured code all that much. Since no one who decides about this sort of thing has given two craps about structure, ever, bad structure is just what we're left with now. The day will come when codebases will be completely unintelligible to humans. The best example is when AI actually refers to code in comments with actual line numbers. No human would ever do that or find that useful if another human did it, because it would be next to impossible for a human to keep the line numbers properly updated after edits and they would soon all be wrong and meaningless. You'd have to go very far back in computing history to get to where we learned not to do that. Was there ever programming with goto's referencing line numbers instead of named labels? If so, this would be that.
boxesnlines 11d ago
I absolutely agree that those things should take priority, but I think those things can only go so far and there's a threshold of complexity beyond which there will always be some benefit to comments. You can absolutely reduce the need for 'signposts' if you avoid creating a maze. As others have said, you didn't always build the maze. Or you built a lovely intuitive path and then were hit with an unexpected new requirement that forced you to add twisty little passages. Or, like me, you're not a perfect being and had to compromise based on some complication you didn't expect.
AIorNot 11d ago
Everyone disagrees about Good Architecture and it changes with new technologies btw Years ago I worked on a project that had a n tier architecture and facade pattern for the frontend It was good architecture for the lead developer who set it up but bad for the new team who need to update the tech So comments and docs are both valuable Nowadays with AI the calculus has changed once more

by jorisw 11d ago

pyrale 11d ago

> Smart developers don’t write mazes. You don’t choose what your forebears have written, though.

jorisw 11d ago
Patching that up by using comments as a 'map' isn't the right way to deal with that. Refactors and rearchitecture are. Putting in comments just helps procrastinate what's necessary.
- stingraycharles 11d ago
  Rewrites require a lot of effort, significantly more than just adding comments. It’s a pragmatic tool until you actually have the time to do the rewrite.
  - jorisw 11d ago
    I never said rewrites. And the more you put in procrastination-encouraging half-solutions, the worse your code base gets.
- adrianN 11d ago
  It's difficult to refactor and rearchitect without first understanding what's there and why.
  - jorisw 11d ago
    And yourself putting in comments is the solution to that?
    - adrianN 11d ago
      It depends on how much time you can spend on the task. If you're allowed to write proper documentation about architecture and requirements that is probably better. If you're just drive-by fixing the code, then good comments are a lot better than nothing.
- pyrale 11d ago
  > Patching that up by using comments as a 'map' isn't the right way to deal with that. There is no right way. Only grey ones that help relieve pain for the team. > Refactors and rearchitecture are. Yeah... if you have the cash and the people. Usually, mature codebases are driven by limited investment with proven business value, because the sweet VC money is no longer there (or never was, in some industries). If you don't, reachitecturing is vanishingly rare, and your refactor budget is limited and you spend it carefully. If a piece of code hasn't moved recently but still comes up frequently when onboarding newcomers, documenting the code may be more profitable and less risky than changing it. It also helps preparing a case for a potential refactor.
misswaterfairy 11d ago
Though the onus is on us to improve what our forebears wrote, for the sake of our own and others' future.
- pyrale 11d ago
  I agree with that. I'm just not sure all of us have the same leeway to improve the codebase, and the cost isn't the same either. When you have less means, you spend them more sparingly.

Tade0 11d ago

I'm afraid this all gets thrown out the window nowadays. Unless I tell them not to, LLMs lean on slapping verbose comments of the worst kind - describing the code instead of the reasons for putting it there. I ask them to write comments in ASD-STE100 Simplified Technical English, but all I really get from that is tersness. Also the other day I stumbled upon a huge pile of documentation and I'm still trying to figure out if it's human or machine written. I stopped reading it half way through as I figured that perhaps it wasn't written for humans to read.

rootlocus 11d ago
The most WTF comments are the ones that describe how the code looked during a rewrite session with no commits. It writes bad code, I ask it to rewrite it, and it leaves a comment saying why the previous implementation was bad, with no history in git of the previous implementation. Edit: changed the LLMs pronoun to it.
- kuschku 11d ago
  Who is this "he" you're talking about? Or were you referring to an LLM? If so, the correct pronoun would be "it". Your english is really good, except for that little mistake.
  - rootlocus 11d ago
    I am 100% guitly of anthropomorphizing LLMs, sorry.
- stakhanov 11d ago
  LLMs do this to communicate with their future selves to avoid retracing what turned out to be the garden path. Another pattern is where they put comments in multiple places in the code to say that those need to be kept in sync in a very particular way ...that sort of thing has always been considered a code smell, but seems to be the post-AI "new normal": it's cheaper for the AI to leave it to its future self to have to make every change in multiple places than it is for its present-day self to do the refactor. Before AI, writing code that worked was costly and structuring it well, while you were at it, didn't increase your cost all that much. Now, AI has reduced the cost of writing badly-structured but working code, while it hasn't reduced the cost of writing well-structured code all that much. Since no one who decides about this sort of thing has given two craps about structure, ever, bad structure is just what we're left with now. The day will come when codebases will be completely unintelligible to humans. The best example is when AI actually refers to code in comments with actual line numbers. No human would ever do that or find that useful if another human did it, because it would be next to impossible for a human to keep the line numbers properly updated after edits and they would soon all be wrong and meaningless. You'd have to go very far back in computing history to get to where we learned not to do that. Was there ever programming with goto's referencing line numbers instead of named labels? If so, this would be that.

boxesnlines 11d ago

I absolutely agree that those things should take priority, but I think those things can only go so far and there's a threshold of complexity beyond which there will always be some benefit to comments. You can absolutely reduce the need for 'signposts' if you avoid creating a maze. As others have said, you didn't always build the maze. Or you built a lovely intuitive path and then were hit with an unexpected new requirement that forced you to add twisty little passages. Or, like me, you're not a perfect being and had to compromise based on some complication you didn't expect.

AIorNot 11d ago

Everyone disagrees about Good Architecture and it changes with new technologies btw Years ago I worked on a project that had a n tier architecture and facade pattern for the frontend It was good architecture for the lead developer who set it up but bad for the new team who need to update the tech So comments and docs are both valuable Nowadays with AI the calculus has changed once more