Good Design is Imperfect Design, Part 1: Honest Names
domainlanguage.com
Good Design is Imperfect Design, Part 1: Honest Names
1–10 of 133 posts
Re: Good Design is Imperfect Design, Part 1: Honest Names
#2I disagree about "plus" in the JodaTime example. The month addition with corner cases did exactly what I expected because the whole library has been polished to "do what a normal human would do, most of the time". A normal human would not suspect Jan + 1 month, is any month other than Feb. However I suspect, not even reading the documentation, if it were fed 30 or 31 days, rather than '1 month', it would also do exactly that, and mostly give dates in March.
Re: Good Design is Imperfect Design, Part 1: Honest Names
#3I disagree about "plus" in the JodaTime example. The month addition with corner cases did exactly what I expected because the whole library has been polished to "do what a normal human would do, most of the time". A normal human would not suspect Jan + 1 month, is any month other than Feb. However I suspect, not even reading the documentation, if it were fed 30 or 31 days, rather than '1 month', it would also do exac…
What is 2021-02-28 + 1 month? Is that 2021-03-28 or 2021-03-31? It is far from obvious what a normal human would do most of the time here.
The lack of associativity is still a problem. If 2021-02-28 + 1 month = 2021-03-28,then (2021-02-28 + 1 month) + 1 month = 2021-03-28 + 1 month = 2021-04-28. While if I ask what is 2021-02-28 + 2 months (given 2021-02-28 + 1 month = 2021-03-31), most people would say 2021-04-30.
While I am not entirely sold on using awkward/"honest" names by default, the author does raise a good point: sometimes concepts are inherently messy or full of important edge cases, and we shouldn't just brush that aside.
I recently ran into a similar problem. I am implementing a distributed lock (https://www.joyfulbikeshedding.com/blog/2021-05-19-robust-di...) -- like a mutex, but works across processes and machines. I try to mimic the language's standard Mutex API as much as possible.
A normal Mutex has a query method named "owned?" to check whether the calling thread owns the mutex. When I tried implementing this method for my distributed lock, it raised a question: owned according to who? Owned according to the local state that represents the lock, or according to the state that lives in the server? Because they can differ (e.g. due to bugs in other clients or because an admin manually messed with the state). So I opted for "honest names" here too and implemented two methods: "owned_according_to_local_state?" and "owned_according_to_server_state?"
Re: Good Design is Imperfect Design, Part 1: Honest Names
#4I disagree about "plus" in the JodaTime example. The month addition with corner cases did exactly what I expected because the whole library has been polished to "do what a normal human would do, most of the time". A normal human would not suspect Jan + 1 month, is any month other than Feb. However I suspect, not even reading the documentation, if it were fed 30 or 31 days, rather than '1 month', it would also do exac…
I found the argument about lack of associativity convincing: it's very counterintuitive that date + 1 month + 1 month is different from date + 2 months
Re: Good Design is Imperfect Design, Part 1: Honest Names
#5Being honest with naming things is also a great roundabout way to ensure you write maintainable, readable code. If the name is honest and it feels awkward, it's a good red flag that there might be a problem with the approach you're taking. I think code golf languages (a-la [0]) are a good example of this approach as well, when your language is as terse as possible, giving very deep consideration to what the language actually does is crucial.
[0] https://github.com/DennisMitchell/jellylanguage/wiki/Quicks
Re: Good Design is Imperfect Design, Part 1: Honest Names
#6I disagree about "plus" in the JodaTime example. The month addition with corner cases did exactly what I expected because the whole library has been polished to "do what a normal human would do, most of the time". A normal human would not suspect Jan + 1 month, is any month other than Feb. However I suspect, not even reading the documentation, if it were fed 30 or 31 days, rather than '1 month', it would also do exac…
What is 2021-02-28 + 1 month? Is that 2021-03-28 or 2021-03-31? It is far from obvious what a normal human would do most of the time here. The lack of associativity is still a problem. If 2021-02-28 + 1 month = 2021-03-28,then (2021-02-28 + 1 month) + 1 month = 2021-03-28 + 1 month = 2021-04-28. While if I ask what is 2021-02-28 + 2 months (given 2021-02-28 + 1 month = 2021-03-31), most people would say 2021-04-30. W…
I think if you try and confuse folks with this, that is easy to do. But, this isn't special. What happens if you add a meter to a kilometer? For most measurements, you get a kilometer. We teach this with significant digits, but then typically ignore it and assume all sorts of conventions that are not spelled out.
If it is important in the domain you are working in, take extra care to understand the maths that you are built on. And don't be surprised to find special cases everywhere.
Re: Good Design is Imperfect Design, Part 1: Honest Names
#7I disagree about "plus" in the JodaTime example. The month addition with corner cases did exactly what I expected because the whole library has been polished to "do what a normal human would do, most of the time". A normal human would not suspect Jan + 1 month, is any month other than Feb. However I suspect, not even reading the documentation, if it were fed 30 or 31 days, rather than '1 month', it would also do exac…
I found the argument about lack of associativity convincing: it's very counterintuitive that date + 1 month + 1 month is different from date + 2 months
One way I suggested that we solve in a different domain was a small name change that really helped. To me "plus" is the _operator_ and "add" is the _operation_. So to me date.add(1 month).add(1 month) is actually different than date.add(2 month) because I can read that as taking two one-month steps which _may_ be different.
Re: Good Design is Imperfect Design, Part 1: Honest Names
#8Classic 'one of the hardest things in Computer Science: naming things'
Re: Good Design is Imperfect Design, Part 1: Honest Names
#9Please don’t have a method named plusIshRoundCeiling() in a library that “might” be used for years in lots of projects :) The plus() one is almost there and you can easily explain the ugly bits in javadocs (with lots of warnings around it so that it sticks out and is addressed hopefully in some next convenient cycle)
Re: Good Design is Imperfect Design, Part 1: Honest Names
#10[deleted]