Missing Hint in Reference

Hi there!

In my language use a Reference is something where really everything is said about a programming language. Recently I learned that new() is possible and just a minute ago I tried a simple template <> and found that this doesn’t even cause a compiler warning.

So, in my view the Reference isn’t really a reference. I think this should be mentioned somewhere at the top.

What do you think?

Gregor

It is a reference of the Arduino 'library', not of C++

Juraj:
It is a reference of the Arduino 'library', not of C++

Well, yes. I think this „limitation“ should be mentioned.

Regards,

Gregor

I agree this is a very big problem that needs to be fixed. When we have a user of 4+ years stumbling across important parts of the language only now, that indicates a serious issue with the documentation.

I used to be of the opinion that the .ino files of Arduino sketches were written in C++ and so we only needed to document this fact so that people could use one of the excellent C++ references that already exist on the Internet (e.g., cplusplus.com to learn C++. This would mean the Arduino Language Reference only needed to document the standard Arduino core API (e.g., digitalWrite()), and perhaps some fundamentals of C++ to get beginners started. I think the Language Reference already does a reasonably good job of documenting the Arduino core API.

My experience when I started with Arduino as someone with very little programming experience was that I started writing sketches following the Arduino Language Reference and quickly hit this point of "That's all there is to the Arduino Language? I need more." Because of this, I was about to abandon Arduino and move on to a more capable microcontroller platform when I found some information on the Forum that made me realize that the entire C++ language was available to me. I wasn't stuck with some kiddie programming language, I was using a standard, professional programming language without even realizing it! That was when I knew Arduino was the right choice for me.

I felt that the Arduino Language Reference could do a better job of making that bridge so that people wouldn't need to stumble upon it by chance. I submitted a suggestion to make some small changes to the reference home page to make it clear that it was C++:

To my surprise, I was informed by several very knowledgeable Arduino employees that .ino files are not written in C++, they are written in Arduino Language, and it would be wrong to tell the readers that it was C++. As an Arduino employee, I am required to share their opinion that there is an Arduino Language. I do understand the reasoning behind saying that .ino files are not C++, since most sketches are indeed not valid C++ code (though it only takes adding a few simple lines of code to make them valid C++).

So now I face this very tricky dilemma. The Arduino Language Reference is the only official documentation of the Arduino Language, but it is far from complete. I think it's essential for a programming language to be completely documented.

The obvious solution is to add to the reference until the complete programming language is documented, but this is a huge task. It also will likely make the reference less friendly to beginners. Dynamic memory allocation and templates are not topics a beginner needs to know about. The upside of the solution of making the Arduino Language Reference comprehensive is that we could write the documentation in a way that is specific to the language's use on microcontrollers. One problem with the C++ references is that they contain information that doesn't apply to Arduino and so you need to read those references with a mental filter to sort out which are the useful bits.

The other idea I've been kicking around lately is to say that C++ is a subset of Arduino Language. Any valid C++ is valid Arduino Language, but not all Arduino Language is valid C++. This would allow us to stick to Arduino's official claim that they invented a new programming language, while still being able to pass off the burden of documenting the entire language on to others.

I'd be very interested in any input on how we can make this situation better.

pert:
To my surprise, I was informed by several very knowledgeable Arduino employees that .ino files are not written in C++, they are written in Arduino Language, and it would be wrong to tell the readers that it was C++.

To quote John McEnroe

You cannot be serious

Next they’ll be trying to convince us that the Earth is an Icosidodecahedron

I think this is a clear case where an employee cannot be bound by some ridiculous and incorrect rule of his employer.

…R

(yes, I looked it up :slight_smile: )

Thanks for your explanation of the situation, pert!

Making documation user friendly surely is hard work. I think that if some documentation isn't complete, that fact should be made clear right at the start.

No matter how experienced someone is -- not telling an important fact in a document that is titled "Reference" is pretty close to a lie. Saying C++ is a subset of any other programming language definitely is a lie.

But that's just two thoughts that popped up whilereading your posting.

Regards,

Gregor

PS: At least it's good that someone else is aware of this not-so-complete-reference-problem.

Before that conversation, I had never heard the opinion that there was an Arduino Language from anyone I felt was qualified. I had only encountered it from beginners and people with no knowledge about Arduino disparaging the project. Meanwhile, I had heard the opinion that there was no Arduino Language from several people who are very knowledgeable about Arduino. I found the "there is no Arduino Language" point of view to be helpful for my own learning process and also convenient for the sake of limiting the scope of the required documentation. But when I had two very knowledgeable people from Arduino tell me there was in fact an Arduino Language it made me realize that I actually have no clue about what the requirements are for a new programming language. I did a little research, but didn't find anything to help me understand this.

So at this point I feel that it's a valid opinion that Arduino's sketch preprocessing is sufficient to create a new programming language.

It's reasonable to expect an employee to "follow the company line" in their work. You wouldn't expect a school to be OK with a geography professor teaching that the earth is an icosidodecahedron.

What I'm still not convinced of is that saying .ino files are written in Arduino Language is beneficial to Arduino users. My personal learning experience tells me this is not beneficial. However, I think it might be possible for us to improve the documentation so that the differences and similarities between the "Arduino Language" and C++ are made clear in a way that is very helpful to the learning process. I'm not sure how to accomplish that, but I am giving it a lot of thought.

pert:
You wouldn’t expect a school to be OK with a geography professor teaching that the earth is an icosidodecahedron.

That’s actually an excellent example.

The objection to the professor teaching that is NOT because it contravenes school policy but because it is UNTRUE.

IMHO same goes for the “Arduino language”

I guess I could go along with “Arduino” being a dialect of C++ (but certainly not the other way around).

And I can see how disguising the use of C++ can be helpful in breaking down the barrier to entry to the Arduino system. Telling someone s/he had to learn C++ before s/he could use an Arduino would not be a good marketing ploy.

I wonder if the Arduino folks have confused themselves because of their (mostly reasonable) enthusiasm for making Arduino programming appear like Processing programming even though Processing is based on Java.

…R

Robin2:
I guess I could go along with "Arduino" being a dialect of C++

That's probably a more accurate/standardized description than my idea of saying C++ is a subset of Arduino Language.

Robin2:
And I can see how disguising the use of C++ can be helpful in breaking down the barrier to entry to the Arduino system. Telling someone s/he had to learn C++ before s/he could use an Arduino would not be a good marketing ploy.

This is definitely something to consider. I don't think it would have mattered to me as a beginner which programming language the documentation claimed, but I did come into it with some prior knowledge of programming. Although I interact with beginners who have no prior programming experience all the time here on the forum, I don't have a sense of whether that would be an issue for them. Perhaps someone who regularly helps beginners learn programming in person would have a better idea.

One thing to note is that the reference does say "The elements of Arduino (C++) code", and has done so for years (maybe from the start), yet I've never seen evidence of that statement causing a beginner problems (even it is a bit confusing to have these vague mentions of "Arduino programming language" and "C++' both in the reference with no explanation of how they relate). According to Arduino, that mention of C++ was an error, but they forgot to fix it even after I unintentionally brought it to their attention.

Robin2:
I wonder if the Arduino folks have confused themselves

I don't think "confused" is an accurate description, but I think they do have a bias in this issue. Creating a new programming language that millions of people use is a very impressive achievement.

pert:
Creating a new programming language that millions of people use is would be a very impressive achievement.

Why not call it, oh, I don't know, something like "Wiring"?

It's a good question. Where does this proliferation of new programming languages end? I'm starting to think I should make one myself; maybe C++ but with line numbers like the good old days of BASIC?

I haven't used Wiring enough to know how much the API has changed. Even if I did know how much it's changed, I couldn't say whether that difference justifies saying that Arduino Language is different from Wiring Language.

Arduino does say this:

To do so you use the Arduino programming language (based on Wiring)

pert:
I don't think "confused" is an accurate description, but I think they do have a bias in this issue. Creating a new programming language that millions of people use is a very impressive achievement.

I believe the word for that is "hubris"

Why are they not content to claim that they have created a system that makes C++ very easy to use. Looked at from that point of view I reckon they have an exportable product that could make C++ programming easier for Newbies on other platforms.

Although I interact with beginners who have no prior programming experience all the time here on the forum, I don't have a sense of whether that would be an issue for them.

I guess I had in mind "Don't you dare touch that Arduino until you have read and learned all of this 453 page text book"

...R

PS ... I have no idea whether any of the C++ textbooks has 453 pages :slight_smile:

PPS ... I came across a language called Rust that is apparently hoping to render C++ obsolete so maybe my remarks are already out of date :slight_smile:

I see this is a question that can be seen from very different view points. But regardless of Arduino being a sub-, superset, dialect or expansion of C(++) I think it should be mentioned there's much more than the things in the reference section.

Regards,

Gregor

Let me fix this for you:

I was informed by several very knowledgeable highly opinionated Arduino employees that .ino files are not written in C++, they are written in Arduino Language, and it would be wrong to tell the readers that it was C++.

:slight_smile:
Of course, there IS a problem, in that if "experienced C++ programmers" show up and try to use the Arduino environment, they are likely to be pretty disappointed. A lot of the stuff that is standard in a C++ desktop environment is NOT present by default on an Arduino. (All of the STL, especially. Exceptions. iostream.) C++ programmers can also be Very Opinionated and would complain bitterly.
C++ == A language syntax and some basics, plus at least the STL, plus a pretty substantial amount of runtime support, plus an approved style. (If you believe that, anyway.)
Arduino == The same language syntax, with an entirely different set of runtime and library support.
Historically, most computer language definitions include a large portion of "library and runtime" code.
C is perhaps one of the few languages that is "pure" in the sense that it can exist with essentially no libraries... (IMO, that's one of the reasons that it has survived as long as it has.)
"PRINT" in Fortran, BASIC, Pascal, etc is part of the language definition. In C, it's a library function that may or may not exist...

As an Arduino employee, I am required to share their opinion

Really? That's sort-of annoying. I recall innovation being very-much driven by internal disagreements, at places I have worked...

Of course, there IS a problem, in that if "experienced C++ programmers" show up and try to use the Arduino environment, they are likely to be pretty disappointed. A lot of the stuff that is standard in a C++ desktop environment is NOT present by default on an Arduino. (All of the STL, especially. Exceptions. iostream.) C++ programmers can also be Very Opinionated and would complain bitterly.

This is where I see a benefit in providing our own 100% complete documentation of the language instead of sending people off to cplusplus.com or cppreference.com with a "good luck". If some things are missing, we leave those out. If some things are only available on certain official boards, then we document that fact.

Perhaps we would need an "Advanced user" switch on the reference home page that reveals the links to the topics beginners should not be thinking about.

pert:
Perhaps we would need an "Advanced user" switch on the reference home page that reveals the links to the topics beginners should not be thinking about.

I think that some kind of „behind the scenes“ or „beyond Arduino“ link would be finde. That may lead to a page where a bit about Arduino's history and its relation to C++ is written.

Regards,

Gregor

pert:
This is where I see a benefit in providing our own 100% complete documentation of the language

That might be nice.

But I don't believe it would be worth the substantial effort that would required.

By the way I am one of those who only uses C/C++ when there is no other option. The Arduino system makes C/C++ a lot more accessible by hiding a lot of the housekeeping. However I am quite content with the idea that I am programming an Arduino in C++. It can see no advantage in pretending otherwise.

C/C++ works very well in the sense that the compilers have been very well developed to generate fast code. However the "user input" side of C/C++ sucks - "how to confuse folk with a minimum of keystrokes"

...R

I'm seeing two possible solutions:

Document only the differences between Arduino Language and C++:

  • Create a new page on arduino.cc that explains the Arduino Language. Provide a short history (Processing, Wiring) of the language. Describe the sketch preprocessing actions that make Arduino Language different from C++ (concatenate .ino files, add #include directive for Arduino.h, generate prototypes). Add a link from that page to an external C++ reference.
  • Add a link at the top of the Language Reference home page to the page about the Arduino Language.
  • Leave the Language Reference content as-is.

Document the entire Arduino Language on the Language reference page. Make no mention of C++.

pert:
I'm seeing two possible solutions:

I much prefer your first suggestion - even if the amount of effort is the same.

Even if there was no "confusion" about whether Arduino is a "language" any proper documentation of the system would include this stuff

Describe the sketch preprocessing actions that make Arduino Language different from C++ (concatenate .ino files, add #include directive for Arduino.h, generate prototypes).

It is a poor reflection on the Arduino folks that that was not written when the Arduino system was first published.

...R

I see a benefit in providing our own 100% complete documentation of the language

  • That would be HUGE.
  • And a "moving target"
  • Both Atmel and Microchip distribute(d) the AVR Gnu C++ compiler without much in the way of "except for xxx" documentation.

Describe the sketch preprocessing actions that make Arduino Language different from C++ (concatenate .ino files, add #include directive for Arduino.h, generate prototypes).

It is a poor reflection on the Arduino folks that that was not written when the Arduino system was first published.

Um. The "hacking" page has been around for quite a long time (and appears to be reasonably up-to-date), and I've always been reasonably happy with their explanation of the Build Process

And, not to point out the obvious or anything, but the Read this before posting a programming question sticky at the top of the "programming questions" topic is a pretty good intro.

Yeah, that isn't all easy to find, or completely obvious. But I bet it's better today than trying to search through 1400-odd pages of "C++ specification that isn't a copy of the C++ specification (because that's copyrighted!)" trying to figure out whether The Arduino Language supports Trigraphs or Nested Namespace Definitions.

(Not to mention the special place reserved in your chosen place of eternal torment for people who read through a language definition looking for "neat features" that they can stick in their program to make it look different from everyone else's...)