My favourite example of confusable methods cost me half a day of debugging. LLVM has two methods on a machine instruction:
isBundle
isBundled
The second was the one I wanted, the first was the one that I had. Renaming this to isInBundle would have made it a bit more obvious and a lot harder to accidentally typo, but even then it’s confusing. Oh, and as I recall, neither had a doc comment (checking now, one does).
There’s one example that isn’t here, which is part-of-speech confusion. The C++ standard library is full of these. The most egregious is .empty() which is a method whose name is both an imperative verb and an adjective. This method, in a sane API, would be called isEmpty to make it clear that it’s predicate that is querying a property of the collection. To make things worse, the classes that have an empty method also have a clear method (another word that is both a verb and an adjective), which does the other one. This is a bit less liable to confusion (I don’t actually know what a clear array would be - one where all of the elements are transparent?) but still not ideal. The OpenStep equivalent of this is called removeAllObjects, which is totally unambiguous. Similarly, C++11’s range-based for loops enforced in the language that both .begin() and .end() have special meanings and must return iterators to the start and end of a collection (rather than begin or end an operation).
The site actually recommends calling things close in a couple of places. That’s interesting because it’s a homonym (which trips up translators periodically, do you mean the verb or adjective?) but by convention it is almost certainly intended a specific one of the two verb forms. Unless you’re writing a flight simulator or similar, when you may want to instruct one object to close on another or measure how close two objects are…
There’s one example that isn’t here, which is part-of-speech confusion. The C++ standard library is full of these. The most egregious is .empty() which is a method whose name is both an imperative verb and an adjective. This method, in a sane API, would be called isEmpty to make it clear that it’s predicate that is querying a property of the collection. To make things worse, the classes that have an empty method also have a clear method (another word that is both a verb and an adjective), which does the other one. This is a bit less liable to confusion (I don’t actually know what a clear array would be - one where all of the elements are transparent?) but still not ideal.
I like what Ruby does: the predicate would be empty? and the clear method would be clear!. I think it originally got this from Smalltalk.
That’s really neat to know; one of the reasons I’ve preferred the Scheme family of Lisps is because they use pred? over predp or pred-p and indicate destructive / mutating operations like reverse! over nreverse.
Some of these go away when programming in a language other than English, where imperatives are spelled differently from infinitives, both different from nouns and adjectives.
I’ve been wondering what a programming language with e.g. Finnish grammar would be like.
That would also be an interesting base-language for translations, since you have much more information in each word. Many translations mistakes are due to confusable English words/forms too.
Quick note: seems like the link submitted does not have the https:// specified, even though the website does have it, which is somewhat annoying if the browser is in https-only mode. Would be nice if that was changed.
I hope they’ll add more of these in the future! I’d consider most on the current list rather obvious, but apparently they still creep in even in widely used code so it’s good to study them anyway so they won’t creep into your code (or your colleagues, if you’re doing code review).
In my experience, ‘vector’ in computing usually means a chunk of repeated data structures that’s contiguous in memory. GPU docs tend to assume the structure is some kind of number, which is how they represent points.
Sometimes I see people doing this when they use the data structure as a function, especially with dictionaries. What I mean is, they use the math definition of a function (maps from some domain to another domain) and then indexing into the structure is like a function call. It can definitely be confusing at first.
The page is somehow pegging a core on my system. I don’t know enough about web development tools to debug why it is doing that, but it feels really weird for that to happen on a page that shows only plain text. Unfortunately can’t read it with scripts disabled either as they use javascript implementation for the tabbed categories.
My favourite example of confusable methods cost me half a day of debugging. LLVM has two methods on a machine instruction:
isBundleisBundledThe second was the one I wanted, the first was the one that I had. Renaming this to
isInBundlewould have made it a bit more obvious and a lot harder to accidentally typo, but even then it’s confusing. Oh, and as I recall, neither had a doc comment (checking now, one does).There’s one example that isn’t here, which is part-of-speech confusion. The C++ standard library is full of these. The most egregious is
.empty()which is a method whose name is both an imperative verb and an adjective. This method, in a sane API, would be calledisEmptyto make it clear that it’s predicate that is querying a property of the collection. To make things worse, the classes that have anemptymethod also have aclearmethod (another word that is both a verb and an adjective), which does the other one. This is a bit less liable to confusion (I don’t actually know what a clear array would be - one where all of the elements are transparent?) but still not ideal. The OpenStep equivalent of this is calledremoveAllObjects, which is totally unambiguous. Similarly, C++11’s range-based for loops enforced in the language that both.begin()and.end()have special meanings and must return iterators to the start and end of a collection (rather than begin or end an operation).The site actually recommends calling things
closein a couple of places. That’s interesting because it’s a homonym (which trips up translators periodically, do you mean the verb or adjective?) but by convention it is almost certainly intended a specific one of the two verb forms. Unless you’re writing a flight simulator or similar, when you may want to instruct one object to close on another or measure how close two objects are…I like what Ruby does: the predicate would be
empty?and the clear method would beclear!. I think it originally got this from Smalltalk.That’s really neat to know; one of the reasons I’ve preferred the Scheme family of Lisps is because they use
pred?overpredporpred-pand indicate destructive / mutating operations likereverse!overnreverse.Thank you! Great examples. I’m adding a todo right now to incorporate these; I’d do it right now if I wasn’t exhausted.
Some of these go away when programming in a language other than English, where imperatives are spelled differently from infinitives, both different from nouns and adjectives.
I’ve been wondering what a programming language with e.g. Finnish grammar would be like.
That would also be an interesting base-language for translations, since you have much more information in each word. Many translations mistakes are due to confusable English words/forms too.
Quick note: seems like the link submitted does not have the
https://specified, even though the website does have it, which is somewhat annoying if the browser is in https-only mode. Would be nice if that was changed.https-only mode doesn’t rewrite it?
At least the one built into Firefox doesn’t.
I hope they’ll add more of these in the future! I’d consider most on the current list rather obvious, but apparently they still creep in even in widely used code so it’s good to study them anyway so they won’t creep into your code (or your colleagues, if you’re doing code review).
I’m assuming the vector represents the position of a target in a coordinate system? How else should that be done?
Oh, no. The term
vectorin this context means something like “resizable list.” In particular, see https://cplusplus.com/reference/vector/vector/ or https://docs.oracle.com/javase/8/docs/api/java/util/Vector.html .Having learned programming first, I got so confused when I first learned linear algebra and saw “vector” used to mean “point.”
In my experience, ‘vector’ in computing usually means a chunk of repeated data structures that’s contiguous in memory. GPU docs tend to assume the structure is some kind of number, which is how they represent points.
Sounds like a synonym antipattern
Sometimes I see people doing this when they use the data structure as a function, especially with dictionaries. What I mean is, they use the math definition of a function (maps from some domain to another domain) and then indexing into the structure is like a function call. It can definitely be confusing at first.
The page is somehow pegging a core on my system. I don’t know enough about web development tools to debug why it is doing that, but it feels really weird for that to happen on a page that shows only plain text. Unfortunately can’t read it with scripts disabled either as they use javascript implementation for the tabbed categories.