5 ms·

To me the most common confusion when reading the code is the lack of documented intention behind the code. You can think of deciphering intention from code as

by sesm 2y ago

To me the most common confusion when reading the code is the lack of documented intention behind the code. You can think of deciphering intention from code as a backwards problem, which is exponentially harder then forward problem (checking if given code is actually doing what's intended). Deciphering intention also gets much harder when there are bugs in the code, and you can't be sure if they are bugs or intentional behavior.

open_ 2y ago
This is quite a valuable comment that I agree with 100% and from what I understand, a highly unpopular opinion. I hope more people see this.
- nerdponx 2y ago
  The idea that code should communicate intent, whether by comments or other means, is popular and common. It ends up being somewhat difficult to execute. In practice, you have to write code like you write prose. Keep your audience in mind, and be aware of the contextual information available to that audience, and write code that will make sense to your particular audience, ignoring the needs of non-audiences. The tricky part is when your audience includes people in the future. But even how you account for a future of missing design docs and broken links will vary based on things like team composition, business/problem domain, is this open-source or not, etc.
- lilfrost 2y ago
  There is consensus documenting why you did something is good (which is what root comment is talking about). Documenting what you did is commonly thought to be a crutch for writing unreadable code.
  - dabraham1248 2y ago
    While I _absolutely_ agree with those sentiments, I have seen nothing like consensus on them myself (in mostly tech startups, but also fintech, and financial (yes, those are different things)). If I limit it to programmers I respect, the percentages go up, but to _maybe_ 75% tops.
  - xboxnolifes 2y ago
    I hate the second thought, because not documenting is clearly not stopping people from committing the unreadable code. Instead we get "my code is self-documenting, I'm not going to write documentation". And as for the third opinion of "the documentation becomes out of date when the code changes", I would prefer slightly incorrect comments to decipher code rather than no comments to decipher code. Doubly so because I can compare the comments to historical revisions.
ykonstant 2y ago
A related problem I have as an amateur is the lack of structure documentation. I clone a repo and try to figure the code out, and I am met with complex folder structures hosting interconnected source files that call functions among them in ways I have to disentangle. There is usually no high level schematic, no bird's eye view documentation, no discussion of the overall flow of execution or the main code paths. Why? I don't understand; twenty-thirty years ago, I was taught to provide visual high level schematics and structural documentation. The latter may be difficult, but surely some schematics with notes on intent cannot be too onerous to draw.
- Dalewyn 2y ago
  I don't think I've ever seen a schematic for a program in all my years programming. Now that you mention it, it really is peculiar given most if not all other schools of engineering have schematics drawn up at some point or another.
  - fluoridation 2y ago
    To be fair, all other schools of engineering concern themselves with constructing actual physical objects, not abstract intangible mathematical structures.
    - jethro_tell 2y ago
      To be fair, our school of engineering has moved from parsing payroll and accounts payable and is now controlling physical objects and their interactions with the physical world, so, its probably time to start taking things seriously like our peers
      - fluoridation 2y ago
        That doesn't make the programmed parts any less abstract, though. That the system as a whole contains physical parts just makes it easier to schematize the system as a whole, not necessarily each individual part by itself.
csours 2y ago
> you can't be sure if they are bugs or intentional behavior. I'm in the middle of a huge legacy codebase and I keep asking two questions: HOW was this working? WAS this working?
macintux 2y ago
I regularly have this discussion when it comes to comments. The intention of the code is much more resilient than the details, so comments should generally focus on the why. (It’s also important to document the code that isn’t there: algorithms that were rejected due to performance, “obvious” enhancements that don’t actually achieve the intended effect, etc.)
juancn 2y ago
Maybe it's me, but I can usually guess intention fairly quickly and also imagine what the thought process was and what kinds of mistakes it probably has. But heck, I'm old and I've been reading other people's code for decades.
__xor_eax_eax 2y ago
And no one ever talks about this. Doing a code review when dropped in cold in SO hard for this reason. Yes, I can tell what you're doing here, but is that what you're SUPPOSED to be doing?

by sesm 2y ago

open_ 2y ago

This is quite a valuable comment that I agree with 100% and from what I understand, a highly unpopular opinion. I hope more people see this.

nerdponx 2y ago
The idea that code should communicate intent, whether by comments or other means, is popular and common. It ends up being somewhat difficult to execute. In practice, you have to write code like you write prose. Keep your audience in mind, and be aware of the contextual information available to that audience, and write code that will make sense to your particular audience, ignoring the needs of non-audiences. The tricky part is when your audience includes people in the future. But even how you account for a future of missing design docs and broken links will vary based on things like team composition, business/problem domain, is this open-source or not, etc.
lilfrost 2y ago
There is consensus documenting why you did something is good (which is what root comment is talking about). Documenting what you did is commonly thought to be a crutch for writing unreadable code.
- dabraham1248 2y ago
  While I _absolutely_ agree with those sentiments, I have seen nothing like consensus on them myself (in mostly tech startups, but also fintech, and financial (yes, those are different things)). If I limit it to programmers I respect, the percentages go up, but to _maybe_ 75% tops.
- xboxnolifes 2y ago
  I hate the second thought, because not documenting is clearly not stopping people from committing the unreadable code. Instead we get "my code is self-documenting, I'm not going to write documentation". And as for the third opinion of "the documentation becomes out of date when the code changes", I would prefer slightly incorrect comments to decipher code rather than no comments to decipher code. Doubly so because I can compare the comments to historical revisions.

ykonstant 2y ago

A related problem I have as an amateur is the lack of structure documentation. I clone a repo and try to figure the code out, and I am met with complex folder structures hosting interconnected source files that call functions among them in ways I have to disentangle. There is usually no high level schematic, no bird's eye view documentation, no discussion of the overall flow of execution or the main code paths. Why? I don't understand; twenty-thirty years ago, I was taught to provide visual high level schematics and structural documentation. The latter may be difficult, but surely some schematics with notes on intent cannot be too onerous to draw.

Dalewyn 2y ago
I don't think I've ever seen a schematic for a program in all my years programming. Now that you mention it, it really is peculiar given most if not all other schools of engineering have schematics drawn up at some point or another.
- fluoridation 2y ago
  To be fair, all other schools of engineering concern themselves with constructing actual physical objects, not abstract intangible mathematical structures.
  - jethro_tell 2y ago
    To be fair, our school of engineering has moved from parsing payroll and accounts payable and is now controlling physical objects and their interactions with the physical world, so, its probably time to start taking things seriously like our peers
    - fluoridation 2y ago
      That doesn't make the programmed parts any less abstract, though. That the system as a whole contains physical parts just makes it easier to schematize the system as a whole, not necessarily each individual part by itself.

csours 2y ago

> you can't be sure if they are bugs or intentional behavior. I'm in the middle of a huge legacy codebase and I keep asking two questions: HOW was this working? WAS this working?

macintux 2y ago

I regularly have this discussion when it comes to comments. The intention of the code is much more resilient than the details, so comments should generally focus on the why. (It’s also important to document the code that isn’t there: algorithms that were rejected due to performance, “obvious” enhancements that don’t actually achieve the intended effect, etc.)

juancn 2y ago

Maybe it's me, but I can usually guess intention fairly quickly and also imagine what the thought process was and what kinds of mistakes it probably has. But heck, I'm old and I've been reading other people's code for decades.

__xor_eax_eax 2y ago

And no one ever talks about this. Doing a code review when dropped in cold in SO hard for this reason. Yes, I can tell what you're doing here, but is that what you're SUPPOSED to be doing?