Comment by motorest
9 months ago
> This may be true for some cases, but I don't see a non-contrived way for code to describe why it was written in the way it does or why the feature is implemented the way it is.
I have to call bullshit on your argument. Either you aren't even looking because you have the misfortune of only looking at bad code written by incompetent developers, or you do not even know what it looks like to be able to tell.
The core principles are quite simple, and are pervasive. Take for example replacing comments with self-descriptive names. Isn't this something obvious? I mean, a member function called foobinator needs a combination of comments and drilling down to the definition to be able to get a clue on what it does. Do you need a comment to tell what a member function called postOrderMessageToEventBroker does?
Another very basic example: predicates. Is it hard to understand what a isMessageAnOrderRequest(message) does? What about a message.type == "command" && type.ToUpperCase() == "request" && message.class == RequestClass.Order ? Which one is cleaner and easier to read? You claim these examples are contrived, but in some domains they are more than idiomatic. Take user-defined type assertions. TypeScript even has specialized language constructs to implement them in the form of user-defined type guards. And yet you claim these examples are contrived?
I'm starting to believe all these vocal critics who criticize Uncle Bob or Eric Evans or any other author are actually talking out of sheer ignorance about things they know nothing about. They read some comment in some blog and suddenly they think they are an authority on a subject they know nothing about.
So much noise.
> Do you need a comment to tell what a member function called postOrderMessageToEventBroker does?
Which event broker? Will I get a response via some callback? What happens if the sending fails, is there a retry mechanism? If yes, how many retries? What happens when the retry count is exceeded? Will the order‘s ID be set by this method? Is the method thread-safe? Which errors can be thrown? „Don‘t call this before the event broker has warmed up / connected“. Etc etc
> Do you need a comment to tell what a member function called postOrderMessageToEventBroker does?
Obviously not and the comment you're replying to hasn't asserted otherwise. They say, clearly, that comments should explain the _why_, postOrderMessageToEventBroker explains only the _what_ (which is reflected in the verbiage of your question). Fortunately comments are practically free and we're not limited to doing the reader one-favor-per-statement, we can explain _both_ the why with a comment (when it's not obvious) and the what with clear function names.
> I'm starting to believe all these vocal critics who criticize Uncle Bob or Eric Evans or any other author are actually talking out of sheer ignorance about things they know nothing about.
I've been programming for 60 years in many different fields. I was programming long before he was. It is possible that I have written more code than he has in more languages (36 at last count), so my criticism of his are based on real-world experience.
What I was refering to was the "why", not the "what" or "how". This is not a good function name to my eye, but YMMV: get-station-id-working-around-vendor-limitation-that-forces-us-to-route-the-call-through-an-intermediary-entity.
Instead, a comment can clearly and succintly tell me why this implementation is seemingly more complex than it needs to be, link to relevant documentations or issues etc.