Go Down

Topic: Missing Hint in Reference (Read 2773 times) previous topic - next topic

gregorss

Jun 09, 2019, 05:12 pm Last Edit: Jun 09, 2019, 05:12 pm by gregorss
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
Nicht lange fackeln, lass' Backen wackeln! (Seeed)

Juraj

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

gregorss

It is a reference of the Arduino 'library', not of C++
Well, yes. I think this ‚Äělimitation" should be mentioned.

Regards,

Gregor
Nicht lange fackeln, lass' Backen wackeln! (Seeed)

pert

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++:
https://github.com/arduino/reference-en/issues/476
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.

Robin2

#4
Jun 09, 2019, 10:56 pm Last Edit: Jun 09, 2019, 10:57 pm by Robin2
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 :) )
Two or three hours spent thinking and reading documentation solves most programming problems.

gregorss

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.
Nicht lange fackeln, lass' Backen wackeln! (Seeed)

pert

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.

Robin2

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
Two or three hours spent thinking and reading documentation solves most programming problems.

pert

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.

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.

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.

AWOL

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"?

pert

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:
https://www.arduino.cc/en/Guide/Introduction
Quote
To do so you use the Arduino programming language (based on Wiring)

Robin2

#11
Jun 10, 2019, 01:04 pm Last Edit: Jun 10, 2019, 01:06 pm by Robin2
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.

Quote
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 :)

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 :)
Two or three hours spent thinking and reading documentation solves most programming problems.

gregorss

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
Nicht lange fackeln, lass' Backen wackeln! (Seeed)

westfw

Let me fix this for you:


Quote
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++.
:-)
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...

Quote
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...

pert

Quote
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.

Go Up