[skybrian]

It’s true that readability is culture-specific, that if the culture were different and people learned different things then different languages would be more readable. But I still think there are differences between languages in the sense of how much you can understand without knowing the definition of every term.

For example, if you’re looking at Lisp code and you don’t know whether an outer term is a function, macro, or special form, you really don’t understand anything inside it except at the most superficial level. It might as well be JSON. Macros aren’t marked, so any unknown term might be a macro. (Knowing the surface syntax is still helpful, though. Well-known syntaxes for data are useful.)

With Forth it’s pretty bad, too. Not knowing what a single word does means that you don’t know what’s on the stack afterwards.

A Unix pipeline is a bit more orderly since you know that there are streams of bytes. You know the command names and the arguments to each command. But if you don’t know what a command does, you don’t know much at all about what the data looks like after that point.

I find currying and point-free programming to be pretty opaque because I can’t tell where the function calls are or how many arguments each function takes from usage. I don’t know what the dataflow looks like. It seems like you need to know some precedence rules too?

Languages with conventional function call syntax, augmented with named parameters, seem better. I can tell where the function calls are and where the inline functions are. Augmented with reasonable names for temporaries, I can make reasonable guesses about what the code does.

These syntax concerns seem independent of whether it’s a functional or imperative language? Making reasonable guesses is what we do when we read pseudocode. Maybe what I’m saying is that some syntaxes seem better for pseudocode than others, and I like languages that look like pseudocode better.

I suspect that these syntax differences also have an effect on how good the error messages are when you screw up.

[kazinator]

> you really don’t understand anything inside it except at the most superficial level

This is true, but:

- the name of the operator is typically a word that you can easily search for in the documentation or on the web, or with "jump to definition" in your editor, if it's something locally defined in the source tree.

- you usually understand the shape of what is inside it. You know what parts of the program you are looking at are arguments to that mysterious operator and which are not. If asked which expression is the third argument of that operator, you can easily find it and know where it begins and ends.

[lispm]

> Macros aren’t marked, so any unknown term might be a macro.

Yes, that's a problem.

There are two clues:

* Macros typically have naming conventions. For example anything beginning with DEF should be a defining macro, not a function. Anything with DO- will be a control structure. Anything with WITH- will be a scoping macro. And so on. Avoid active names like CREATE- and use DEFINE- instead. CREATE-CLASS would be a function, DEFINE-CLASS would be a macro.

* In source code the enclosed code typically has syntax and special indentation, when used with macros. Functions have certain uniform indentation rules.

    (create-class 'container-ship
                  :superclasses '(ship)
                  :slots '((max-number-of-containers :type integer))
                  :documentation "our new container-ship class")

Above is a function and uses one of the typical formatting/indentation rules for functions. Line up the arguments. Start with the required argument and then the named argument pairs (name, arg).

The macro looks different. The first important things like name and superclasses are on the first line. The other parts of the class specification follow and are indented by two characters.

    (define-class container-ship (ship)
      ((max-number-of-containers :type integer))
      (:documentation "our new container-ship class"))

Developers who write macros should make it clear what a macro is, by using hints like these.