Getting rid of terminology
Gustavo Niemeyer
gustavo.niemeyer at canonical.com
Thu Mar 10 14:33:48 UTC 2016
Hello,
I've been sitting in the pedantic terminology room again while going
through some code, and would like to propose we kill the usage of some
terms in our code base as being either confusing or just unnecessary and/or
unhelpful for the comprehension of the logic we have in place.
Some justification and proposal goes with each suggestion:
-- Part
This term as previously discussed was one of the types that were used to
refer to snaps. Let's use Snap or SnapInfo where appropriate.
-- Bag
That's usually a type with an underlying slice type. If the problem is
sorting, the suggested approach is to use a private type that is used only
for the specific sorting, and providing the result as the pure slice type
still. When having a slice is really necessary as an exported type, which
is very rare, the suggested approach is to simply use the plural instead of
the Bag suffix (Foos instead of FooBag).
-- Origin
Per the new terminology, that's the snap developer, so let's use that
instead. This perhaps the only thing in this list that is worth doing in
time for 16.04, as we have this term leaking through public APIs.
-- FullName
-- QualifiedName
Both of these mean almost the same thing: a snap name with a snap developer
suffix. Having two terms for the same idea sounds bad, so we should at
least unify them, but I actually suggest killing both in favor of using the
name of the individual terms themselves. If that sounds strange, note that
"qualified" of "full" could just as well include the revision, or the
version, or anything else that is a core property of the snap. It only
becomes clear after an explanation, so perhaps we can just avoid it
altogether.
For code, I suggest introducing the NameDotDev method to go next to Name
itself for the Snap.
- Best (as an adjective)
I think there's a single use of this that John is already killing now, but
using that chance: this is usually a poor adjective for APIs and might be
hinting at loosely defined or too-specific behavior. A better term would
indicate why something is "Best" so consumers of the API and future readers
of the code have an idea about what's going on without having to introspect
doc or code.
Sounds reasonable?
Will keep you posted on future ideas on the theme.
gustavo @ http://niemeyer.net
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/snappy-devel/attachments/20160310/3fd52348/attachment.html>
More information about the snappy-devel
mailing list