Feedback for article on how I ported my web app from React to Elm

[benhoyt]

Hi good Elm folks! I’d love some feedback on my draft article Learning Elm by porting a medium-sized web frontend from React before I post it further afield. I had a lot of fun learning Elm (kudos Evan) and really like it overall. There’s also some (hopefully constructive) criticism in there. If anyway has any thoughts, feedback, corrections – please let me know.

[rupert]

I found this section interesting, because I have had thoughts along similar lines myself:

"
Here’s the current List.filterMap documentation:

    filterMap : (a -> Maybe b) -> List a -> List b

    Filter out certain values. For example...

And here’s what it could be:

    filterMap : (a -> Maybe b) -> List a -> List b
    filterMap convertFn input = ...

    Filter out values of the input list where `convertFn` returns
    None. For the values where it returns `Just b`, include in the
    output list. For example...

"

In some language docs there is special syntax for describing the parameters of functions or methods. The one I am most familiar with is Javadoc, which has @param for example. So in Elm it could be:

    filterMap : (a -> Maybe b) -> List a -> List b
    filterMap convertFn input = ...

    @param convertFn  Function that returns None for elements to exclude form the result, or Just to include them.
    @param input      The input list.

Documenting the parameters can be helpful in situations where there are multiple parameters of the same type, since order is important.

[benhoyt]

Documenting the params in a list would be one way, and I think helpful, but to me it looks very Java-ish as is. I prefer how Python does this, by just using normal prose but italicizing the param names in the text. For example: https://docs.python.org/3/library/functions.html#filter

[G4BB3R]

I did not finish reading, but I think LOC measurement is wrong. Elm code is more vertical, React is more horizontal. Is possible to measure both projects using valid characters count, excluding comments? I am very curious to know the real comparison.

[benhoyt]

Yeah, I mention some of the reasons in the text – I don’t think React is necessarily horizontal, but the way I wrote it with fairly long lines is. Still, that’s only part of the reason – the other reasons are type definitions, imports, elm-format.

I actually tried counting whitespace-separated words as I thought it might be a better measure. (Comments are included, but I have very few comments in either codebase.) But counting by words it’s slightly worse – I think because Elm / elm-format uses a good amount of white-separated punctuation, like [ ( foo , bar ) ].

• React: 6031 words
• Elm: 15,331 words

By counting non-whitespace characters, it’s somewhat closer:

• React: 50,243
• Elm: 79,934

[pdamoc]

The words and lines of code comparison of Elm and a non-statically typed language is flawed because Elm has type annotations.

Elm also encourages the use of functions which means even more type annotations.

So, if you want a fair comparison, look at Elm vs React in ReasonML.

My intuition tells me that if one wants to play code golf and removes the type annotations and just compensates for “body on the next line” rule of elm-format, the number of lines will get a lot smaller.

In the case of elm-spa-example there might also be a difference in scope of the implementations. Richard’s implementation is highly didactical presenting a lot of patterns that have more to do with maintainability of the code. If he would have aimed at least lines of code, his approach would have been somewhat different.

[choonkeat]

Thanks for writing the article @benhoyt ! I re-lived my early confusions through it

I had the same sentiment, yearning for meaningful argument names, when reading function signatures. I’d +1 on all the points raised by this article under “Documentation”

Additionally, I’d also like to point out that example code in elm docs like to use unqualified function names when referring to functions of the current module, an example in Json.Decode

decodeString (index 1 string) json  == Ok "bob"

(aside: I’d initially kept tripping over that loose string or int; forgetting that they are not types…)

The target audience of example code in docs is actually not the author of the current package. Developers are looking at your docs for sample code to write in their own modules, e.g. Main.elm

:. as much as possible, sample code should be written with qualified imports.