Exceptional Naming(kevlinhenney.medium.com)
kevlinhenney.medium.com
Exceptional Naming
https://kevlinhenney.medium.com/exceptional-naming-6e3c8f5bffac
2 comments
I don’t like your technique because:
1- As you say yourself, there is some amount of subjectivity about when « handleX » is the best description (when the effect is extensive enough) and when it is not.
2- The whole point of calling handlers « handleX » is that you DO get to know what happens when the event X happen: you just have to read the content of « handleX » function.
So here is my solution: follow conventions. If your handler is a simple thing like « setServer » you’ll see that the function content is one line of code. If it’s more complex, you will see it also.
It works 100% of the time, ensures that people won’t loose their mind reading your code, and prevent useless debates about form.
1- As you say yourself, there is some amount of subjectivity about when « handleX » is the best description (when the effect is extensive enough) and when it is not.
2- The whole point of calling handlers « handleX » is that you DO get to know what happens when the event X happen: you just have to read the content of « handleX » function.
So here is my solution: follow conventions. If your handler is a simple thing like « setServer » you’ll see that the function content is one line of code. If it’s more complex, you will see it also.
It works 100% of the time, ensures that people won’t loose their mind reading your code, and prevent useless debates about form.
The idea of signals and slots is a loose, flexible coupling, so I think that the connect() is the perfect place to read about what causes what. It seems like your expectations come from something like virtual interfaces (in the C++ sense) - these often have a limited amount of implementations on both sides that "know" each other more closely.
There’s two problems, naming is hard and people think it doesn’t matter, that it’s just semantics or bike shedding when actually it’s probably one of the most important things.
Naming things correctly is as important as well written code itself, it’s all about communication.
I really liked the demonstration of how you can make exception names more explicit.
Naming things correctly is as important as well written code itself, it’s all about communication.
I really liked the demonstration of how you can make exception names more explicit.
> just semantics
To expand on this, I think we can drop the "just". Conveying semantics is one of the core benefits of using a high level language.
Modern languages have recognized this and promote conventions that are more in line of what the author is suggesting.
Go and Rust tell a story about re-usable interfaces/traits. Naming is even more important here, since an overly specific name for an interface would make it confusing to use it in different context (which has stronger support since you can supply interfaces/traits on the consumer side of a type).
The exception examples are indeed very good and well reasoned. The context is implied and even enforced by language constructs here.
On the other hand there are cases where explicit verbosity is useful, not necessarily in regards to naming:
I sometimes like branching logic to be explicit, so you don't need to understand all of the execution context (by reading/testing the code) to understand an isolated branch.
Another case can be data modelling. Temporal records can provide a transaction_from and a transaction_to field so the record explicitly states its temporal validity in isolation.
Being explicit here is more verbose but has benefits for reasoning. I assume this is the intent of the (overly) explicit naming convention in Java et al. But it goes too far too often.
To expand on this, I think we can drop the "just". Conveying semantics is one of the core benefits of using a high level language.
Modern languages have recognized this and promote conventions that are more in line of what the author is suggesting.
Go and Rust tell a story about re-usable interfaces/traits. Naming is even more important here, since an overly specific name for an interface would make it confusing to use it in different context (which has stronger support since you can supply interfaces/traits on the consumer side of a type).
The exception examples are indeed very good and well reasoned. The context is implied and even enforced by language constructs here.
On the other hand there are cases where explicit verbosity is useful, not necessarily in regards to naming:
I sometimes like branching logic to be explicit, so you don't need to understand all of the execution context (by reading/testing the code) to understand an isolated branch.
Another case can be data modelling. Temporal records can provide a transaction_from and a transaction_to field so the record explicitly states its temporal validity in isolation.
Being explicit here is more verbose but has benefits for reasoning. I assume this is the intent of the (overly) explicit naming convention in Java et al. But it goes too far too often.
> just semantics
One plus two equals two, if by "plus" we mean "times".
It's just semantics! ... the semantics of the word "plus".
One plus two equals two, if by "plus" we mean "times".
It's just semantics! ... the semantics of the word "plus".
Sometimes I see signals and slots named like this:
I prefer to name them like this:
The bad example is a strawman, but my point is that, if the signals and slots are well named, one can see in the connect() "if X changes then Y happens". Such naming is not always possible, because sometimes, the effects of a change are extensive enough that "handle X changed" is the best reasonably short and unchanging description.