4 ms·

Which is easier to comprehend at a glance? * Under my Foo API you are able to combine Bars monoidally * Under my Foo API you are able to combine Bars using ba

by tome 9y ago

Which is easier to comprehend at a glance? * Under my Foo API you are able to combine Bars monoidally * Under my Foo API you are able to combine Bars using baz such that `baz (baz bar1 bar2) bar3 == baz bar1 (baz bar2 bar3)` for all `bar1, bar2, bar3 :: Bar`, and also `baz == Bar quux baz == Bar baz quux` for all `baz :: Bar`.

Terr_ 9y ago
* Under my Foo API you are able to combine Bars just like adding numbers. But seriously, the use of Bar/Baz etc. in this example makes it more convoluted, rather than less, precisely because the names offer no hint for how to understand the nature of each thingy.
- tome 9y ago
  > Under my Foo API you are able to combine Bars just like adding numbers. No. Firstly, Bars may not be commutative. Secondly, would you really say that taking the unions of sets is "just like adding numbers"?
rbehrends 9y ago
How often do you document an API in such a way? Does the frequency with which this occurs justify introducing new terminology? Plus, you artificially inflated the wording to make "x is associative and has a neutral element y" look more complicated than it actually is, while not even naming in your "short" case what the operation and neutral element are.
- tome 9y ago
  > How often do you document an API in such a way? Every time `instance Monoid Foo` occurs in the Haddock documentation of a Haskell datatype which is pretty often! > Does the frequency with which this occurs justify introducing new terminology? "Justify" according to what set of criteria? Personally I prefer it. > you artificially inflated the wording to make "x is associative and has a neutral element y" look more complicated than it actually is So your suggestion is * baz is associative and quux is a neutral element for it Really, if you're going to go that far you may as well go all the way and just say * Foo is a Monoid under baz and quux > while not even naming in your "short" case what the operation and neutral element are. Well, in the Haskell world they're implied by the typeclass instance, but I take your point.
- marcosdumay 9y ago
  If you are writing Haskell, you document your code this way first¹, and what is missing from this kind of definition you write down with words. It's incredibly useful, since you can just go into Hoogle or some similar tool and query a function that: Monoid m => (a -> m) -> [a] -> m And it will tell you it's called `foldMap`, and is available by default. Not long ago I have made this exact query because I forgot the name. 1 - Well, the autodoc write those comments for you.
- romwell 9y ago
  I think at this point, I'll settle on "code people like taking fancy words from math people and running with them". Associativity is a boring word, because high-schoolers have seen it. Eh. Your patience here is admirable.
Veedrac 9y ago
"`baz` is associative and `quux` is an identity element." (Though normally the latter would be more like "`quux` is a noop", "`quux` is an empty set", or whatever domain-specific term you need, and the associativity claim would be a brief parenthetical inside meaningful documentation.)
dmitriid 9y ago
It depends on what knowledge you have. To me "monoidally" could just as well be "bryllyg"[1] for all it's worth. I think jQuery satisfies monoids most of the time, and it worked and could be explained just fine without saying the word "monoidally" even once. [1] From Jabberwocky, of course
romwell 9y ago
How about this: "Under my Foo API, Bars are combined associatively". Associativity is a word. It's also a word that is taught to people in high schools. So use that.
- tome 9y ago
  That's absolutely fine. Then you also have to mention that there's an identity element. Once you've used the words "associatively" and "identity" it's no longer scary to use the word "monoid" so you may as well use it.
  - romwell 9y ago
    Well, you still have to use the words "associativity" and "identity" when you describe the operation and say what the identity element is. You can't just say that you can "combine" elements "monoidally" for it to mean anything. Also, the elements are still combined associatively. With closure and and identity properties, the set forms a monoid under this operation. "Monoidness" is not a property of operation (in a way that the language is usually used, at least in math). For that matter, "combine monoidally" is a phrase that has 2 Google hits at the moment, which indicates to me that in real life, you still have to resort to less-shiny words to describe things.
    - tome 9y ago
      > You can't just say that you can "combine" elements "monoidally" for it to mean anything. ... For that matter, "combine monoidally" is a phrase that has 2 Google hits at the moment, which indicates to me that in real life, you still have to resort to less-shiny words to describe things. There doesn't seems anything hugely objectionable to me in saying "Bars combine monoidally". But if you prefer, one can say "Bar forms a monoid under baz and quux". It may not be obvious to you that it increases simplicity merely to combine two words into one but across an ecosystem of perhaps a thousand Monoid instances it indeed is.

by tome 9y ago

Terr_ 9y ago

* Under my Foo API you are able to combine Bars just like adding numbers. But seriously, the use of Bar/Baz etc. in this example makes it more convoluted, rather than less, precisely because the names offer no hint for how to understand the nature of each thingy.

tome 9y ago
> Under my Foo API you are able to combine Bars just like adding numbers. No. Firstly, Bars may not be commutative. Secondly, would you really say that taking the unions of sets is "just like adding numbers"?

rbehrends 9y ago

How often do you document an API in such a way? Does the frequency with which this occurs justify introducing new terminology? Plus, you artificially inflated the wording to make "x is associative and has a neutral element y" look more complicated than it actually is, while not even naming in your "short" case what the operation and neutral element are.

tome 9y ago
> How often do you document an API in such a way? Every time `instance Monoid Foo` occurs in the Haddock documentation of a Haskell datatype which is pretty often! > Does the frequency with which this occurs justify introducing new terminology? "Justify" according to what set of criteria? Personally I prefer it. > you artificially inflated the wording to make "x is associative and has a neutral element y" look more complicated than it actually is So your suggestion is * baz is associative and quux is a neutral element for it Really, if you're going to go that far you may as well go all the way and just say * Foo is a Monoid under baz and quux > while not even naming in your "short" case what the operation and neutral element are. Well, in the Haskell world they're implied by the typeclass instance, but I take your point.
marcosdumay 9y ago
If you are writing Haskell, you document your code this way first¹, and what is missing from this kind of definition you write down with words. It's incredibly useful, since you can just go into Hoogle or some similar tool and query a function that: Monoid m => (a -> m) -> [a] -> m And it will tell you it's called `foldMap`, and is available by default. Not long ago I have made this exact query because I forgot the name. 1 - Well, the autodoc write those comments for you.
romwell 9y ago
I think at this point, I'll settle on "code people like taking fancy words from math people and running with them". Associativity is a boring word, because high-schoolers have seen it. Eh. Your patience here is admirable.

Veedrac 9y ago

"`baz` is associative and `quux` is an identity element." (Though normally the latter would be more like "`quux` is a noop", "`quux` is an empty set", or whatever domain-specific term you need, and the associativity claim would be a brief parenthetical inside meaningful documentation.)

dmitriid 9y ago

It depends on what knowledge you have. To me "monoidally" could just as well be "bryllyg"[1] for all it's worth. I think jQuery satisfies monoids most of the time, and it worked and could be explained just fine without saying the word "monoidally" even once. [1] From Jabberwocky, of course

romwell 9y ago

How about this: "Under my Foo API, Bars are combined associatively". Associativity is a word. It's also a word that is taught to people in high schools. So use that.

tome 9y ago
That's absolutely fine. Then you also have to mention that there's an identity element. Once you've used the words "associatively" and "identity" it's no longer scary to use the word "monoid" so you may as well use it.
- romwell 9y ago
  Well, you still have to use the words "associativity" and "identity" when you describe the operation and say what the identity element is. You can't just say that you can "combine" elements "monoidally" for it to mean anything. Also, the elements are still combined associatively. With closure and and identity properties, the set forms a monoid under this operation. "Monoidness" is not a property of operation (in a way that the language is usually used, at least in math). For that matter, "combine monoidally" is a phrase that has 2 Google hits at the moment, which indicates to me that in real life, you still have to resort to less-shiny words to describe things.
  - tome 9y ago
    > You can't just say that you can "combine" elements "monoidally" for it to mean anything. ... For that matter, "combine monoidally" is a phrase that has 2 Google hits at the moment, which indicates to me that in real life, you still have to resort to less-shiny words to describe things. There doesn't seems anything hugely objectionable to me in saying "Bars combine monoidally". But if you prefer, one can say "Bar forms a monoid under baz and quux". It may not be obvious to you that it increases simplicity merely to combine two words into one but across an ecosystem of perhaps a thousand Monoid instances it indeed is.