Suggested improvements to the home page text

[per1234]

https://www.arduino.cc/reference/en

Arduino programming language can be divided in three main parts: structure, values (variables and constants), and functions.

Change:

Arduino programming language can be divided in three main parts

To:

Arduino's programming language (C++) can be divided in three main parts

Reasoning:
There is widespread misunderstanding that there is an "Arduino Programming Language". The original text could make a beginner think this. My suggested change is consistent with the existing description text for the Structure section: "The elements of Arduino (C++) code."

---

Change:

structure, values (variables and constants), and functions.

To:

functions, values (variables and constants), and structure.

Reasoning:
This is the order the sections appear on the page.

[SimonePDA]

Dear Per, sorry, but I don't agree about your "There is widespread misunderstanding that there is an "Arduino Programming Language". The original text could make a beginner think this."
Indeed the Founders created an Arduino Language (based on Wiring) and implemented it in C++. Arduino Language has its own data types and functions. We call it everywhere Arduino Language and it is not a misunderstanding, but one of the elements of Arduino.
I will investigate why we have this "The elements of Arduino (C++) code." sentence that is not how it should be.

Simone

[SimonePDA]

You can find some details about Arduino Language history here...

https://www.arduino.cc/en/Guide/Introduction

[per1234]

Indeed the Founders created an Arduino Language (based on Wiring) and implemented it in C++. Arduino Language has its own data types and functions. We call it everywhere Arduino Language and it is not a misunderstanding, but one of the elements of Arduino.

We'll have to agree to disagree on that. I stick with this viewpoint:
https://hackaday.com/2015/07/28/embed-with-elliot-there-is-no-arduino-language/
Claiming there is an "Arduino Language" is only harmful to the Arduino users and cheapens this great project. One of the great things about Arduino is that it uses a standard, professional programming language, rather than some "toy language".

You can find some details about Arduino Language history here...
https://www.arduino.cc/en/Guide/Introduction

That's a blank page. Caused by some error in the website?

EDIT: The page is working now

---

Relevant forum comment I stumbled across today:
http://forum.arduino.cc/index.php?topic=88924.msg671018#msg671018

when I first looked at what appeared to be the Arduino "language" as presented on the reference page it put me off and I went looking at other platforms.

At the time though there weren't any good other platforms (IMO) so I came back to Arduino and delved a bit deeper. Then of course I realized that there are no real restrictions on what you can do, it's just C/C++.

That is almost the exact experience I had when I started thinking of getting more serious with my Arduino hobby, except by the time I came along there were decent alternatives.

Related:

• https://forum.arduino.cc/index.php?topic=235811.msg1696149#msg1696149
• http://forum.arduino.cc/index.php?topic=392195.msg2701193#msg2701193

[SimonePDA]

I have to ask the Founders their opinion on this topic. I'll get back to you here. I'm not in the position to agree or disagree on such an important issue.

[pnndra]

Hi Per,
Arduino Language is NOT C++. even if in the end it is translated to C++ and compiled with C++ it IS a language by itself which actually is of course very close to pure C++ but also adds a few subtle differences that at first may put you off as an experienced programmer but on the contrary help beginners to focus on what they want to achieve rather than on syntax, sematics etc.

It is very important that as part of the Arduino team you recognize the importance of these differences because these are what make Arduino so widespread. to be honest i have been perplexed myself on the necessity to "restrict" user to a init and loop function as well as to the need for a preprocessor that in a way limits what you can do but after i better understood the design choices behind this everything became clearer.

i recognize that some of these topics are a bit difficult to digest, especially without too much documentation on the background but maybe we can gather some more docs and discussion threads you may want to read to better understand the reasoning behind this.

[matthijskooijman]

Hm, came upon this issue after seeing mention of the "Arduino language" in some new documentation. Might be a bit late, but I still want to add my viewpoint.

I also consider that the concept of "the Arduino language" might be more confusing than helpful to users. It is true that Arduino offers a number of custom types, objects and functions that allow expressing sketches easily and portably. However, I would say that all these are the API offered by Arduino, they do not constitute a language (in the same way that e.g. the STL, or std::string is not part of the C++ language, but offered as a standard library alongside it).

Looking at the language that Arduino allows in its .ino files, this is pretty much completely C++, except that:

• Functions do not need forward declarations, because these are autogenerated by the IDE.
• Arduino.h is automatically included.
• .ino files are concatenated before compilation.
• Libraries to be used are automatically detected based in #include directives.

These are really just a small preprocessing step that does not change the code significantly. One can say this step "translates" the "Arduino language" code to C++, but IMHO that suggests this step is a lot more involved than it really is.

Even more, deciding which libraries to use is not something that is really part of the language, but part of the build system around the language, so that part does not actually change the language in any way.

So technically, I do not think the Arduino language is significantly different from C++.

Of course, what is technically the case is not necessarily the same in the perception of users. In particular, most users will probably think of the core API as part of the language, so in that sense it might be useful to talk about the "Arduino language'.

However, in my perception it is harmful trying to hide the fact that this language is really just C++ with an API. I can imagine that really novice users might be somewhat helped by this sheltered treatment when they stay within the Arduino reference documentation to see what is possible within Arduino. But there quickly comes a point where the Arduino reference documentation is not sufficient, because the user needs something that is undocumented, because the documentation is incomplete about details, because the user runs into a compilation error that they do not understand. When they do, it is helpful when they realize that they are really just coding in C++, since that opens up a a whole world of extra documentation, tutorials, stackoverflow posts, etc. to them.

I've seen this happen a lot in the #arduino IRC channel where we get a lot of novice users looking for help. Regularly, users wonder what things they can or cannot do in this "Arduino language", and usually it is an eye-opener to them when we tell them they're just coding C++.

I'm not sure this is the right place for this, but I would suggest to reconsider this position. In particular:

• Where appropriate, make it more explicit that Arduino uses C++ with some limited preprocessing and a builtin API / core interface, instead of a completely separate language of its own.
• Consider alternatives for the term "Arduino language". Maybe something like "Arduino programming environment" would be better (which would refer to the APIs and language constructs available to a sketch, not so much the IDE itself, so it's not quite a perfect term). Maybe there are better terms available.

Update: Made my list of preprocessing steps complete

[SimonePDA]

Hello @matthijskooijman,
this is a topic that goes back to the origins of Arduino and is something that has been discussed already so many times.
Also this time I have to "summon" the founders because it is something that is under their responsibility.
@mbanzi, @tigoe or @dcuartielles might have something to say about this topic.

[tigoe]

I'll defer to David and Massimo, but I am fine with "Arduino API", as long as someone comes up with a good succinct explanation for beginners as to what an API is. Life's too short and too precarious to debate things like this, for me at least.

[ThePirate42]

I guess I'm late to the discussion, but what about something like "Arduino dialect" or "Arduino C++ dialect"? For a beginner dialect is probably clearer than API, but there is an implication of being a dialect of something.