[blumomo]

As a person who can visually see, I want to emphasize that these goals: short methods (max 40 LOCs) and speaking names for all code entities are equally important to me. I want to spend as few time as possible reading the code. I want to spend most time on modifying and transforming the code. I do so by building up a mental model which I can change freely before typing the changes down. Sometimes it helps to write down the ideas to see how they "look like", however everything you say applies equally well to me as a non-blind programmer.

Another important trait of easy to read code is the rule of "Big picture" first. I.e. if you have a `main()` method you will find it first in my files, only then followed by sub methods which are called by main(). Same holds for types: first comes the class and then it's followed by any type which might be required for a class attribute. So, when opening a file you immediately get the big picture and depending on the granularity you want to build for your mental model you can continue reading by scrolling down. When the model is good enough, you can skip the rest of the file.

I find this pattern to the contrary of how others design their files. There are people who list all details and sub methods first before telling me only further down the road how these details are put together. This forces me to read a lot of code to build a blown up mental model which might not be necessary for the current task at hand.

[loup-vaillant]

I've just written a little parser I OCaml, and the file goes like this:

  Module declarations                         ( 3 lines)
  Parser type declaration                     ( 1 line )
  Implementation details you don't care about (47 lines)
  Actual grammar                              (20 lines)

In that order. In Haskell, I would probably have put the grammar at the top of the file, so you can get the big picture right away. But the language reads stuff from top to bottom, so I have to put the big picture at the bottom.

An alternative would be separate the details from the grammar, but then I would expose those implementation details in an interface, while in fact the rest of the program is only interested in one function that parses everything.

Or, you could write from bottom to top. It's OCaml, so you know the big picture cannot be at the top. Now a case could be made for a language that reads toplevel statements from bottom to top…

[beefhash]

To be fair, C is kind of like that, too. You could move the declarations of static functions to the top, but then you'd still have declarations that prevent you from getting to the real meat.

[akavel]

That and poor/nonexistent syntax for macros are about my only 2 serious gripes I have with OCaml. The third was missing multithreading, but IIIC this seems to kinda be workable now with lwt IIUC?

[nikisweeting]

In my career I have found programmers generally fall into two camps:

- those that prefer high-level overviews first, then drill down to learn details later

- those that want to thoroughly understand each smaller building block first before dealing with bigger picture concerns

For example, I jump right into projects and skim the docs and start hacking stuff together without learning the nuts and bolts, whereas my cofounder likes to read the theory behind the library, then read the source code before even starting to write a single line that uses the library. Both approaches are valid, I've just found most people tend to strongly prefer one approach or the other, and it's helpful to identify what a person's preferred approach is when working with them.