peerreynders

peerreynders

And there was a time where people thought Hungarian Notation was a great idea until they realized that it became an impediment to necessary change.

I was just grateful that the documentation is quite up front about when something is a macro.
I’m talking about (macro) to the right - in front of the link </> to the source - I always quickly scan over there to know what I’m dealing with.

2
Post #21
tmbb

tmbb

The problem is not confusing functions with macros. The problem is confusing macros (and theoretically functions) with special forms

0
Post #22
tmbb

tmbb

The syntax reference seems almost perfect. I’d add a list of keywords that create blocks (do, else, etc) because I can’t find those documented in official sources.

0
Post #23
josevalim

josevalim

Creator of Elixir

They are in the do/end blocks in the Syntax Reference. All other keywords are operators.

0
Post #24
rvirding

rvirding OP

Creator of Erlang

Yes, and no!

Some of the pages you reference, operators, guards and unicode syntax, would fit in what I would call a language reference. The syntax reference, however, would not. It is mainly a description of the AST and only indirectly a language reference. While it is interesting if I want to write macros or write my own source transformations the AST is uninteresting to those who want to learn the syntax and it clutters up the text. So definitely keep it but not as part of a language reference.

Re the discussion of macros. For a language reference knowing whether something is a macro is actually not very interesting. At most all you would need is a tag saying whether it is a special form or a macro. What confuses the matter is alternate forms for do ... end (which unless you haven’t already guessed it I think is bad idea :wink:) but you could just describe both alternatives without going deeply into why.

3
Post #25
matiso

matiso

Agree. For the tiny benefit of writing some one-liners, you get 2 ways of doing the same thing. It confuses newcomers and makes code written by different people often times inconsistent.

1
Post #26
DianaOlympos

DianaOlympos

IIRC it is not for any “benefit”. It is a consequence/side effect of own the parser and the AST works.

But it was not “added” for one liner. I may be wrong or badly remember.

0
Post #27
tmbb

tmbb

Since we’re bikeshedding about syntax, I actually prefer the keyword list with block contents delimited by parenthesis to do ... end.

The one line form is less verbose and more consistent with the way the function is defined.

0
Post #28
peerreynders

peerreynders

Not sure I understand what you mean and it may just be my personal preference but I like to have a very clear understanding/separation between generative, compile time and runtime effects. Preprocessors often aren’t considered “part of the language” and their syntax is typically so different that it’s very clear what has an effect before the code hits the compiler.

In Elixir’s case macros are such an integral part of “the language as it’s employed” that it takes a lot more conscious effort to differentiate “source code” with compile time effects versus runtime effects.

The confusion experienced by newcomers is simply a warning sign that they are approaching Elixir with an ill-fitting mental model. As such that confusion should be exploited as an opportunity to explain in what ways Elixir is different from other languages.

So while superficially def looks like a keyword from Ruby or Python the moment they look at the documentation (which I think isn’t a completely unreasonable expectation) alarm bells should go off.

def(call, expr // nil) doesn’t look anything like “function definition syntax” - I’d say it looks more like a code generation directive. This is also the perfect opportunity to drive home the fact that imperative languages make heavy use of statements while functional languages tend much more towards expressions.***

Once newcomer’s have sorted out that difference, they’ll comfortably fall back to treating def ... do ... end just like a “definition” while not being confused by def ... , do: ... and they’ll also be better prepared to deal with any other misunderstandings that they are bound to discover in their journey ahead.

*** I find it discouraging how often Elixir/Erlang educational material uses the term “statement” when “expression” is correct. For example, there is no case statement, only a case expression - if you choose to ignore the returned value then that is your own business.

4
Post #29
Azolo

Azolo

I felt like this when I read the syntax section too. It’s not that it isn’t good information or isn’t relevant overall. It’s just that when I read it I kept thinking, “This is a very good overview of how the parser works, but how will this help from getting a compile time syntax error?”

Honestly, everything I would expect in a Syntax section is basically just a collection of summaries about important things to the language. Then each thing easily links to the relevant section that has the rest of the information.

e.g.

  • The Kernel module is imported automatically
  • import/2 allows one to easily access functions or macros from others modules without using the qualified name
  • defmodule is used to declare new modules
  • def is used to declare new named functions and can only be used with defmodule
  • A series of single quoted characters is a list of codepoints. A series of double quoted characters is a binary.
  • etc…

Basically all things that could provide a quick refresher or if I am trying to debug some Elixir code and have never really messed with the language.

1
Post #30