3 ms·

Agree. I find, what you usually want to understand is not the "what" or "how" but the "why", and that is quite a bit harder to automate than translating syntax

by kleiba 4y ago

Agree. I find, what you usually want to understand is not the "what" or "how" but the "why", and that is quite a bit harder to automate than translating syntax into natural language statements.

Gordonjcp 4y ago
I caused a bit of an "incident" at a web dev company I worked at many many years ago by removing commit access from one of the "technical managers", whose hobby was removing every single comment he could find. "But the code shouldn't need comments," he'd complain, "it should be obvious what it does otherwise it's just bad code!" Yes, you dobber, it *is* obvious from the code, the *how* is obvious, but the why and the what might not be. The comments explain what it's doing stuff to and why, and in particular why you'd want that and why it's important. Disk space is free, so in a big long comment just write up what that particular bit of business logic is intended to achieve and what it expects as inputs and outputs. or, TL;DR "DOCSTRINGS BITCH DO YOU SPEAK IT"
- more-coffee 4y ago
  I bet they also pulled out the "but the code will change and then the comments become invalid, or even gasp misleading"?
  - Gordonjcp 4y ago
    Absolutely, and could not be convinced that if the code and comments got out of sync then it was likely that the function name would no longer make sense, and that's when we get real trouble. There were horror stories with that codebase, like index.php was set as the default error handler, started by immediately returning 200 OK before going anywhere near URL dispatching, and then displaying a page that said 404 despite returning 200 if it couldn't find the URL.
Quekid5 4y ago
Yeah, the 'why' often literally doesn't exist as information in the code anywhere, e.g. business rules, domain-specific knowledge, etc. If you're extremely lucky it might exist as 'why comments' :) I do wonder if ML could be applied if you actually also train it on your particular (large) application where if might be able to 'cross-reference' domain knowledge present in commented code to other similar code. (But then you might want to just remove the pseudo-duplication anyway.)

by kleiba 4y ago

Agree. I find, what you usually want to understand is not the "what" or "how" but the "why", and that is quite a bit harder to automate than translating syntax into natural language statements.

Gordonjcp 4y ago

I caused a bit of an "incident" at a web dev company I worked at many many years ago by removing commit access from one of the "technical managers", whose hobby was removing every single comment he could find. "But the code shouldn't need comments," he'd complain, "it should be obvious what it does otherwise it's just bad code!" Yes, you dobber, it *is* obvious from the code, the *how* is obvious, but the why and the what might not be. The comments explain what it's doing stuff to and why, and in particular why you'd want that and why it's important. Disk space is free, so in a big long comment just write up what that particular bit of business logic is intended to achieve and what it expects as inputs and outputs. or, TL;DR "DOCSTRINGS BITCH DO YOU SPEAK IT"

more-coffee 4y ago
I bet they also pulled out the "but the code will change and then the comments become invalid, or even gasp misleading"?
- Gordonjcp 4y ago
  Absolutely, and could not be convinced that if the code and comments got out of sync then it was likely that the function name would no longer make sense, and that's when we get real trouble. There were horror stories with that codebase, like index.php was set as the default error handler, started by immediately returning 200 OK before going anywhere near URL dispatching, and then displaying a page that said 404 despite returning 200 if it couldn't find the URL.

Quekid5 4y ago

Yeah, the 'why' often literally doesn't exist as information in the code anywhere, e.g. business rules, domain-specific knowledge, etc. If you're extremely lucky it might exist as 'why comments' :) I do wonder if ML could be applied if you actually also train it on your particular (large) application where if might be able to 'cross-reference' domain knowledge present in commented code to other similar code. (But then you might want to just remove the pseudo-duplication anyway.)