5 ms·

How can you lose readibility to something else? Can't you comment what a tricky bit of code does? Full disclaimer, I'm a fairly novice programmer.

analog31 9y ago
I'm hardly a guru, but I think that a tricky code, with an explanation. invites a number of subtle problems. You end up having to prove that the code and its explanation actually agree with one another. For instance your explanation could be crystal clear, but the code could still contain a bug, that's harder to see because it's tricky. Or, someone could update the code and not the explanation.
khedoros1 9y ago
Consider the case when someone is prototyping a hardware device. They might start out with a bunch of separate modules connected by wires, with the benefit that those modules can be reconnected in different ways easily, and the connections are relatively clear. Later, they'll do the work to custom-build a circuit board, chips, and all that to make a marketable product. One problem: The finished product is much harder to modify than the prototype was. We expect software to be more malleable. There are a lot of ways to architect software that will increase efficiency in some way but will make it harder to modify the software in the future (adding new features, closing security holes, etc). On top of that, code that's tightly tied together becomes harder to read. Comments are great, but they've got to be maintained too, except that you don't have customers or compilers/parsers/etc enforcing that. So if a bunch of code is complicated, has a lot of inter-relationships between different pieces, etc, then part of the job is making sure that the comment is up-to-date and still correctly describes the purpose and use of the code. Clever, hard-to-read bits of code should be as small and far apart from each other as possible. Maintainability includes more aspects than just readability.
- SimbaOnSteroids 9y ago
  That's a great answer thank you for your response, do you think it would be possible to write a plugin that auto comments code and updates the comments for particularly tricky parts say something that comments [n] then tacks on what n does at the end of the code. Then in the background keep a running list of what got referenced where and updates those references as needed?
  - khedoros1 9y ago
    The rule of thumb is that comments should explain the "why", and the code itself should explain the "how", so I tend to be skeptical of documenting how something works in the comments. Say that we've got that 1% case that's irreducibly complex (i.e. clarifying/simplifying the code kills the performance of something that gets run a million times a second), where we might want to explain the "how" because the code's unclear but can't be changed. The comment itself might take the form of pseudocode representing the slower-but-clearer version of the code. Being a complex and sensitive area, you'd want to have as many tests built around it as possible, to verify that the behavior doesn't change unless it was planned in advance. Part of the code-review would be that any change in behavior (as reflected by changes to the tests) would also need to be documented in the comments. Computers are good at accurately tracking multitudes of small details (like automatically tracking all the places a piece of code is called, etc). Getting them to synthesize a summary of something's behavior ("seeing the forest instead of just the trees", the kind of thing that would be useful as a code comment) sounds like it would be interesting to research, but I don't think there's anything like that right now.

analog31 9y ago

I'm hardly a guru, but I think that a tricky code, with an explanation. invites a number of subtle problems. You end up having to prove that the code and its explanation actually agree with one another. For instance your explanation could be crystal clear, but the code could still contain a bug, that's harder to see because it's tricky. Or, someone could update the code and not the explanation.

khedoros1 9y ago

Consider the case when someone is prototyping a hardware device. They might start out with a bunch of separate modules connected by wires, with the benefit that those modules can be reconnected in different ways easily, and the connections are relatively clear. Later, they'll do the work to custom-build a circuit board, chips, and all that to make a marketable product. One problem: The finished product is much harder to modify than the prototype was. We expect software to be more malleable. There are a lot of ways to architect software that will increase efficiency in some way but will make it harder to modify the software in the future (adding new features, closing security holes, etc). On top of that, code that's tightly tied together becomes harder to read. Comments are great, but they've got to be maintained too, except that you don't have customers or compilers/parsers/etc enforcing that. So if a bunch of code is complicated, has a lot of inter-relationships between different pieces, etc, then part of the job is making sure that the comment is up-to-date and still correctly describes the purpose and use of the code. Clever, hard-to-read bits of code should be as small and far apart from each other as possible. Maintainability includes more aspects than just readability.

SimbaOnSteroids 9y ago
That's a great answer thank you for your response, do you think it would be possible to write a plugin that auto comments code and updates the comments for particularly tricky parts say something that comments [n] then tacks on what n does at the end of the code. Then in the background keep a running list of what got referenced where and updates those references as needed?
- khedoros1 9y ago
  The rule of thumb is that comments should explain the "why", and the code itself should explain the "how", so I tend to be skeptical of documenting how something works in the comments. Say that we've got that 1% case that's irreducibly complex (i.e. clarifying/simplifying the code kills the performance of something that gets run a million times a second), where we might want to explain the "how" because the code's unclear but can't be changed. The comment itself might take the form of pseudocode representing the slower-but-clearer version of the code. Being a complex and sensitive area, you'd want to have as many tests built around it as possible, to verify that the behavior doesn't change unless it was planned in advance. Part of the code-review would be that any change in behavior (as reflected by changes to the tests) would also need to be documented in the comments. Computers are good at accurately tracking multitudes of small details (like automatically tracking all the places a piece of code is called, etc). Getting them to synthesize a summary of something's behavior ("seeing the forest instead of just the trees", the kind of thing that would be useful as a code comment) sounds like it would be interesting to research, but I don't think there's anything like that right now.