For indentation and very mechanical formatting, I suggest just using something like hindent, brittany or ormolu (all available at your local Hackage). For naming, I follow Chris Done's suggestion: https://chrisdone.com/posts/german-naming-convention/ On Sat, 19 Sep 2020, at 4:32 PM, Misja Alma wrote:

Thanks, these links are really useful! This definitely answers part of my question.

But what would still be really useful are some more or less generally accepted best practices about variable naming, indentation, when to use nested functions vs when to prefer keeping functions short, etc with regards to readability.

On Sat, 19 Sep 2020 at 17:10, Henning Thielemann wrote:

...

On Sat, 19 Sep 2020, Misja Alma wrote:

...

Does anybody have any tips, or are there some sites or books that I could read about this topic?

It may be a bit old but we have some articles on style in the Haskell Wiki: https://wiki.haskell.org/Category:Style https://wiki.haskell.org/Category:Idioms

_______________________________________________ Haskell-Cafe mailing list To (un)subscribe, modify options or view archives go to: http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe Only members subscribed via the mailman list are allowed to post.

...

For naming, I follow Chris Done's suggestion: https://chrisdone.com/posts/german-naming-convention/

Thanks! I didn't know it had this funny name, but the German name convention is also widely used in the Java world. But I wonder how well it works in Haskell, because unlike Java, in Haskell a lot of stuff can happen in a single line. With those long variable names, you'd have to break those lines several times. I haven't tried it yet, but I wonder how readable that is in Haskell? Or am I looking at the wrong problem here, and should I first of all try to have as little happening in a single line of Haskell as possible? On Sat, 19 Sep 2020 at 18:22, Oliver Charles wrote:

For indentation and very mechanical formatting, I suggest just using something like hindent, brittany or ormolu (all available at your local Hackage).

For naming, I follow Chris Done's suggestion: https://chrisdone.com/posts/german-naming-convention/

On Sat, 19 Sep 2020, at 4:32 PM, Misja Alma wrote:

Thanks, these links are really useful! This definitely answers part of my question.

But what would still be really useful are some more or less generally accepted best practices about variable naming, indentation, when to use nested functions vs when to prefer keeping functions short, etc with regards to readability.

On Sat, 19 Sep 2020 at 17:10, Henning Thielemann < lemming@henning-thielemann.de> wrote:

On Sat, 19 Sep 2020, Misja Alma wrote:

...

Does anybody have any tips, or are there some sites or books that I could read about this topic?

It may be a bit old but we have some articles on style in the Haskell Wiki: https://wiki.haskell.org/Category:Style https://wiki.haskell.org/Category:Idioms

_______________________________________________ Haskell-Cafe mailing list To (un)subscribe, modify options or view archives go to: http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe Only members subscribed via the mailman list are allowed to post.

main :: IO () main = Q.getContents -- raw bytes & AS.parsed lineParser -- stream of parsed `Maybe Int`s; blank lines are `Nothing` & void -- drop any unparsed nonsense at the end -- [1] & S.split Nothing -- split on blank lines & S.maps S.concat -- keep `Just x` values in the sub-streams (cp. catMaybes) & S.mapped S.sum -- sum each substream & S.print -- stream results to stdout

There's still quite a bit that can be improved here. First of all: comments are good. But whenever you write a comment, ask yourself "could I choose a better name instead?" Make the code self-documenting at all usage sites by choosing a good name once. It's a good idea for every language, but this piece of code is a good example of how to apply it. So, first step: main ∷ IO () main = Q.getContents & parseLines & dropUnparsed -- Add the explanation/link definition side & splitOnBlankLines & catMaybes' -- why write "it's catMaybes", when you could just write "catMaybes"? & S.mapped S.sum & S.print Do you need more functions this way to store the names? Yes. Which is a good thing, because they might be reusable. Of course there's a limit; if every function fits in half a line, you've probably gone too far. Second step: Thinking from left to right is a remainder from thinking imperatively. If you just turn around the top level of the code, the reader is forced to a game of ping pong while reading, so it can even make it harder to understand. So let's get rid of that (&) crowbar. main ∷ IO ()main = S.print     . S.mapped S.sum     . catMaybes' -- by the way, there's probablya better name for what it's actually doing. "dropBlankLines", maybe?      . splitOnBlankLines      . dropUnparsed     . parseLines     $ Q.getContents There's more reasons why going against Haskell's natural grain is a bad idea, and you provided the perfect hook to talk about it:

(|>): a -> (a -> b) -> b (|.>): (a -> b) -> (b -> c) -> c (|$>) f a -> (a -> b) -> f b (|*>) f a -> f (a -> b) -> f b

Operators have the inherent problem that there aren't many symbols to choose from. That means that almost all operators are overloaded. For example, (|>) will be confused with the one from Data.Sequence. Yes, there's unicode. I love unicode (see that sneaky little "∷" up there?) so I've tried using Unicode in operators before, but one single person using the project had their device set to a C locale and so my whole library was search-and-replaced. It's still 1968 out there, so there's like 10 symbols to choose from. And even if you could use more symbols, operators still have the inherent problem that they can't contain any letters. What exactly does (>>?$>) mean? Or (|>||>)? Or (<<*>@)? So why not rely on the operators that are widely used instead of crowbaring new ones in just so that we can keep programming in C.

Am 19.09.20 um 18:22 schrieb Oliver Charles:

For naming, I follow Chris Done's suggestion: https://chrisdone.com/posts/german-naming-convention/

FWIW, I tend to disagree with the position presented in this blog, at least in the generality in which it is stated. Yes, long names can be useful to enhance readability, but this is mostly the case when naming highly specific things. In Haskell, core algorithms often implement some algebraic theory. It is not by accident that mathematical formulae, including applications in the natural sciences, almost exclusively use single letters or very short names. Understanding such formulae at a glance requires familiarity with the notational conventions used, but once you have achieved that familiarity, the short names actually /improve/ readability, assuming the naming convention is applied in a consistent manner. It is also no accident that formulae typically make up only a part of the complete text. A complex formula needs to be accompanied by precise definitions and explanations. Whenever you write code for which it is not immediately obvious why it was done in exactly this way, add a comment that explains what is going on! To illustrate my point, here is some code that implements a highly non-trivial algebra I wrote some time ago: https://hub.darcs.net/darcs/darcs-screened/browse/src/Darcs/Patch/V3/Core.hs... I think using longer names in this code would be awkward and distracting. Also note that the naming convention is documented: https://hub.darcs.net/darcs/darcs-screened/browse/src/Darcs/Patch/V3/Core.hs... I even introduced operator symbols +| and -| as synonyms for some Data.Set operations in order to make the formulae more concise (and thus, IMHO, easier to read). It goes without saying that you cannot read non-trivial code like this as you read english prose. There is simply no way to understand it without having at least a rough idea of the underlying theoretical foundations. Cheers Ben

True, but it might have something to do with the fact that mathematics was invented long before monospaced fonts. And hand-writing integrals, or quantifiers, or the empty-set symbol, is just as easy as writing digits. I would rather agree with Ben: there are lots of places where long identifiers are distracting. Sometimes they make sense, but a lot of times they just don't.

On 20 Sep 2020, at 14:02, Ignat Insarov wrote:

Ben, I think your proposition is righteous and uncontestable in theory, and I stand by you. Unfortunately the practice hardly aligns with the sermon.

No one writes Mathematics in monospace ASCII left to right. They go to great lengths to actually type set things, generously use large and small font, bold and cursive, write above and below the line, use Greek and Hebrew and a myriad infix symbols. And for a reason — compare a latex source of a _«notation heavy»_ paper with it rendered.

One may approach mathematical style in program source with generous use of Unicode, but few dare. Even type setting code in proportional font is considered heresy by many — just so that they may banish proper tabulation and _indent with spaces_. So, even the proponents of the mathematical style do not care to follow it as soon as it requires a little effort. _(Hoω h∀rd may it be to g∃t some ∪nic⊕de on one's kεyb∅arδ? See also the packages `base-unicode-symbols`[1] and `containers-unicode-symbols`[2].)_ Therefore I think for many it is merely an excuse for writing ugly code.

The Darcs code you show illustrates the point Chris Done speaks for as well. Observe top level names: `displayPatch`, `commuteConflicting`, `cleanMerge` — quite German! Then there is `ctxAddInvFL` and `mapFL_FL`, but that from other modules. Finally, I tried to find out what `Prim` stands for — I went as far as to the index of `darcs` on Hackage[3] but no luck. And `prim` is the most frequent in the list of words of the module, with 125 occurrences in normalized case. Primitive? Primary? Prime? Primavera?

[1]: https://hackage.haskell.org/package/base-unicode-symbols [2]: https://hackage.haskell.org/package/containers-unicode-symbols [3]: https://hackage.haskell.org/package/darcs-2.16.2/docs/doc-index-P.html _______________________________________________ Haskell-Cafe mailing list To (un)subscribe, modify options or view archives go to: http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe Only members subscribed via the mailman list are allowed to post.

Am 20.09.20 um 14:02 schrieb Ignat Insarov:

The Darcs code you show illustrates the point Chris Done speaks for as well. Observe top level names: `displayPatch`, `commuteConflicting`, `cleanMerge` — quite German!

Yes, top level functions are typical candidates for longer names. I am not opposed to the "german notation" in any way, I just don't think it is always appropriate to use this style for every variable, including function parameters, as suggested in the blog.

 Then there is `ctxAddInvFL` and `mapFL_FL`, but that from other modules.

Well, sometimes you have to compromise between legibility and conciseness, especially when distinguishing between variants. The FL and RL sequence types are ubiquitous in our code base and the convention of suffixing a function with them to indicate what type of parameter it takes is well established. I wouldn't want to write out "monoidConcat" instead of "mconcat" everywhere. (Or would that have to be "semigroupConcat" nowadays? Thankfully we could avoid bikeshedding this to death...) Or "foldRight" or even "foldAssociatingRightwards" instead of "foldr".

Finally, I tried to find out what `Prim` stands for — I went as far as to the index of `darcs` on Hackage[3] but no luck. And `prim` is the most frequent in the list of words of the module, with 125 occurrences in normalized case. Primitive? Primary? Prime? Primavera?

Your first guess was correct ;-) Though I doubt that knowing this helps to understand the code better. Knowing that 'log' is short for 'logarithm' doesn't help you understand a formula containing 'log' unless you already know what 'logarithm' means. Long "german" names don't relieve you from the task of familiarizing yourself with the problem domain and its concepts and conventions. As regards type setting and unicode symbols, I am not a great fan of that stuff. IMO it makes no sense to mimic mathematical style in any literal sense. The point of a formula is not that it contains fancy special notation. Rather, the point is to avoid distracting the reader with irrelevant details. The only difference between a mathematical formula and a (functional) program is that the latter can be (efficiently) executed by a machine, *in addition* to being read and understood by humans. Besides, a lot of notational conventions in mathematics are not well suited to programming or formally proving things. Many (if not most) constructs that traditionally have special notation in math (e.g. sum, integral, etc) are subsumed by the concept of a higher order function. This has been well-known for several decades now, but the mathematical community is extremely conservative with its established notation. My personal explanation for this phenomenon is that all the existing work in math (books, papers) serve as a giant "standard library for the math language" and changing established notation would mean a huge effort in factorizing (i.e. re-writing) most of that existing work. That said, there are cases where a graphical notation is actually better suited for abstracting irrelevant details than the equivalent textual formula. The most well-known example for this is category theory with its arrow diagrams. As I found out a few years ago, patch theory is another instance where an arrow diagram is often more succinct and less cluttered than the textual formula. Ever since I wished I could include such diagrams directly in the code. Here is an example where I used ASCII graphics to explain a fairly complicated piece of code: https://hub.darcs.net/darcs/darcs-screened/browse/src/Darcs/Repository/Merge... This crutch clearly has limits: to picture a three-way merge you need to move from squares to cubes which gets quite annoying to do in ASCII. Cheers Ben

As a person who has been trying to learn Haskell for years I have a private joke related to reading Haskell source which is “It has been x days since I’ve seen completely unintelligible Haskell.” My sense is that language extensions are a big part of this - they can have a significant impact on readability and for a novice it is not at all clear how to differentiate the text changes wrought by the extension. And in the presence of multiple or even many extensions? Forget it. So yes, I agree Haskell can be hard to read - and we haven’t even dredged up the point/point-free debate! With Kindness, Brody On Sat, Sep 19, 2020 at 08:33 Misja Alma wrote:

Thanks, these links are really useful! This definitely answers part of my question.

But what would still be really useful are some more or less generally accepted best practices about variable naming, indentation, when to use nested functions vs when to prefer keeping functions short, etc with regards to readability.

On Sat, 19 Sep 2020 at 17:10, Henning Thielemann < lemming@henning-thielemann.de> wrote:

...

On Sat, 19 Sep 2020, Misja Alma wrote:

...

Does anybody have any tips, or are there some sites or books that I

...

could read about this topic?

It may be a bit old but we have some articles on style in the Haskell

Wiki:

https://wiki.haskell.org/Category:Style

https://wiki.haskell.org/Category:Idioms

_______________________________________________

Haskell-Cafe mailing list

To (un)subscribe, modify options or view archives go to:

http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe

Only members subscribed via the mailman list are allowed to post.