Why is this page not more detailed? I'm sure a lot of FAQ forum posts would've gotten their answer if that page was a bit more detailed. Maybe comparing arduino to more that just Processing?
Why is there nothing about strings / char arrays, which is definitly a source of a lot of the FAQs?
Why is there no examples of object initialization and use?
Why is it so that under 'Loops' , Arduino and Processing are differenciated?
Under 'Printing' why is this:
int i = 5;
Serial.print("i = ");
Serial.print(i);
Serial.println();
Not written as:
int i = 5;
Serial.print("i = ");
Serial.println(i);
Which it could, and I think it should should.
No need to emphesise the need for multiple print statements?
And all this, is, ofcourse minor insignificant details, but I just had to ask. And, I'll gladly help! :
The main documentation is not intended to teach all there is to teach about C. Nor, in my opinion, should it try.
Agreed that char vs char[] vs char* vs "chars" should be better documented, but admittedly, it's one of the most bizarre things about C vs any other high-level language that just hides all this complexity.
I don't think the main documentation really wants to educate about C++, the many ways of developing object-oriented code, how constructors work, and so on, either. It documents the methods required to use the included libraries. Serial.begin(9600); done. All else is outside the scope of newbie orientation and library reference.
If I understand the history of the library before I joined, the println() method did not always have all the one-argument overloads, so you originally needed to use print(x) and println() separately. Now it's just a matter of style.
As much as you want to show the tightest possible code on the reference, I think there's a balance to be made. The code examples should be informal and simple, and optimization should be far from the top priority. Learn the basics, then learn how to improve. And by all means, don't expect arduino.cc to be the only resource for learning C, C++ or general software development best practices.
I do not expect arduino.cc to be tha best source for learning c/c++ but I do expect it to continue being the best learrning enviroment for microcontrollers.
I think a comparison between Arduino and Processing on how to initiate objects is at it's place in the comparison.
Many new programmers come from a processing/java 'background'. I've often seen Class var = new Class(); in Arduino code.
The Comparison page could've just added something like:
Arduino
Processing
Class var();
Class var = new Class();
By the way, I agree on all your points about the what the reference should be, and how it should be done. But I do not se any harm in extending the arduino reference a bit. Or generally adding documentation.
As for your quick example, I prefer Foo foo = Foo(); over Foo foo(); -- it's partly a matter of style and readability, but also makes the compiler errors more self-explanatory if the arguments don't match any known constructor. The latter looks just like a prototype of a function that returns a Foo instance, and some compilers will start complaining later when you're trying to abuse what it thinks is a function pointer.
