some of this discussion reminds me of things i was taught/read
the bell labs writer course talked about using simple language, that there's so much technical jargon, that it can't be completely avoided, but should be minimized. this echoes what a college professor said about writing at a 3rd grade level
the other comment comes from Bjarne Stroustrup 3rd ed. of his book where he encourages only using the features of the language that were necessary .. presumably because many coders were not familiar with the more esoteric features and would make the code more difficult to review and maintain.
at least on this forum, i believe most programs can be implemented with mostly C features, even though some think even those features are too much for newbies and those types of programs are easier to understand
Perhaps. I was mainly concerned about the suggestion regarding making member variables const. Maybe I got a bit carried away.
I do think though that many (if not all) best practices should be followed in tutorials. If people pick up bad habits along the way, it will be one step forward, two steps back.
Maybe we can think about a best practices tutorial (that other tutorials could build upon).
Not too familiar with ESPs but I believe they are 32 bit processors so,
how much memory is used to store a uint8_t? If uint8_t X was stored at memory location, say, 0xC000, would the next declared uint8_t Y be stored at 0xC0001 or 0xC004? When the processor fetches a uint8_t does it fetch a 32 bit block and discard the upper 24 bits? Is there any advantage in using "bytes" as opposed to declaring everything a 32 bit "int"?
That would almost certainly result in a long drawn out discussion about what constitutes good practice and hence should be included, with no conclusion being reached.
For instance, I consider that putting each { and } alone on its own line is good practice, but as I see from your suggestion about using braces for one line code blocks (which I agree with), that is not your preferred style. Needless to say, I consider (know) that you are wrong
We can indeed discuss style until the cows come home, but when it comes to using different constructs, there may be some convincing reasons to prefer one over the other.
That said, we have already exchanged our differences of opinion about the use of macros, templates and other stuff.
In this Arduino Forum, a Newbie is one who has just taken the membership of the Forum having no experience in programming and hardware or a learner or an active/retired Software/Hardware Engineer (the Mentor).
A Beginner is one who has just taken membership of the Forum to learn microcontroller architecture and its interfacing through procedural programming.
I understand that a Tutorial posted (to be posted) is aimed at the Beginners; if so, the structure of the sketch will correspond to the activation of the corresponding hardware based on Arduino IDE and Arduino UNO.
In order to present a Tutorial, I would adhere to the following template:
Declaration of global variables
Declaration of user-defined functions
void setup()
{
}
void loop()
{
}
Definitions of the user-defined functions
That’s not needed always and adds clutter for beginners.
I’m not in favor of « you’ll understand later why but do it like this for now » type of approach as you create frustration and a sense of black magic complexity to an important topic. Curious minds will get annoyed by this and will want to know why and the other will just get confused or worse disengaged.
My (limited) experience in the Arduino environment is that it’s better to explain this only when this becomes needed (probably later with separate compilation units / a function calls a function that the compiler has not seen the declaration or definition of yet) and learning this upon failing.
If you teach general programming in C or C++ with coding homework in a terminal on a computer, writing the main() function etc then you don’t have the training wheels of the IDE and then you need to introduce this concept early.
So Either you don’t want to address the «complexity» of why this is important and you rely on the IDE doing that for you in the .ino file or you want to nail this skill upfront and it’s a good opportunity to discuss functions, signature and what a compiler does.
I’ve been explaining this with role play. You hide a candy in an empty drawer in the classroom. You take two students and whisper to one of them « the lollipop (or whatever it is) is in the bottom right drawer of the teacher’s desk » and don’t give any clue to the other. And then you unveil to both of them the order getTheHiddenObject() from the blackboard or a piece of paper or just tell them that’s the instruction they need to execute.
Of course the one with no information does not know what to do and the other Student who has been told ahead of time what to look for and where the object is hidden will go right there.
Then the discussion on what happened is easy and you had a fun moment in class. I’ve done that with something the student can keep (a lollipop when they were trendy - you can use healthy food nowadays like a carrot :)) and when later on the students hit the issue they refer this as the "lollipop bug" and everyone know what this is because of the anchoring exercise.
Teaching is an art and a science as well; whereas, training is a pure science. Is Arduino Forum a Teaching/Training Platform?
In teaching, the teacher goes top-to-bottom and bottom-to-top or whatever ways he finds effective to convey the essence of a topic to the major portion of the pupils.
In training, the trainer has to follow sequentially a set of pre-tested steps to convey the skills to all the participants; else, he is liable to account to his Manager for the unsuccessful trainees.
In between there were quite a few posts leading to a general discussion of "teaching" and "training". I will take the opportunity to publish my personal opinion on this topic and also on the use of the Arduino forum in one of the next posts.
So just a view words in advance:
You are completely right of course regarding the ESP32 which I used in Wokwi and the general consideration of the microcontroller architecture when using certain data types.
However, a tutorial (at least in my opinion) usually focuses on a specific topic. It should not lead you in the wrong direction, but also not cover too many aspects at once, so that you do not lose the overview. Otherwise you run the risk of getting bogged down.
That's why I think the consideration of the microcontroller architecture could be a good topic for a separate tutorial!
My view of these things (I may be wrong, of course) is as follows:
Arduino Forum:
The Arduino Forum is a social platform for people interested in microcontroller technology.
It serves the exchange of information, knowledge and mutual support in overcoming problems in this field.
The forum is therefore neither a teaching nor a training platform, even if knowledge and skills are improved through the above exchange. Otherwise, the processes associated with teaching and training would have to be introduced and formal requirements for "teachers" would have to be set and reviewed.
Tutorials:
The content listed under "Introductory Tutorials" is of course subject to certain rules, has to be usable and must not contain incorrect or erroneous information.
These tutorials cannot fulfill the very specific requirements for teaching and training, because this generally requires that
information about the level of knowledge of the participants is available and
feedback between teacher and participant(s), which is used for corrective or supplementary intervention and/or exams.
Other online tutorials, too, can only fulfill the requirements of teaching and training by preselecting participants and checking their success.
In this respect, Arduino tutorials are exclusively offers for self-learning.
Contents of Tutorials: (in my opinion and in the spirit of the above):
Tutorials of this kind should focus on a specific topic and should be as short as possible in order
not to stress the attention and receptivity of the readers
to cover an interesting topic without drifting into breadth or depth
They should take into account the general rules of knowledge transfer:
from the simple to the difficult
from the known to the unknown
present the subject in understandable language
The Tutorials may be written differently based on the assumed level of knowledge of the target audience.
I am aware that the texts in my post #2 need improvement in these areas. And as my time permits, I will strive to make progress.
My intention was to get feedback very quickly and that definitely worked
This is an interesting deviation from the topic, probably necessary to clarify things...
@ec2021
I re-checked your examples. You have incorporated lot of the suggestions. Imho it's time to notify moderators to move #2 to Tutorials. Your work is already in the upper 50% of good tutorials on my personal list. You can improve and expand the examples anyway later.
At the risk of sounding pedantic (again), in sketch 9 (With Class III) both the declaration and the implementation reside in the same header file ledType.h. This will eventually lead to problems when the header is included twice or when it is needed in different compilation units.
To solve the first problem, you can include the following line at the start of the header file:
#pragma once
Or you can add an include guard as explained here (this seems to be recommended):
The second problem can be solved by separating the declaration and the implementation. In this case, the following can stay in ledType.h,
class ledType {
// This class declaration and everything in it can stay.
};
and the rest of the content, starting from this line,
ledType::ledType(uint8_t pin, unsigned long on, unsigned long off) {
goes to ledType.cpp.
In the following example, adapted from your sketch, the file test.cpp was added and the suggested changes were applied.
You may want to try adding test.cpp to the original sketch to see what happens. To see the relevant errors, include Arduino.h to get rid of the uint8_t errors first.
I wou;d give students pointers after arrays to complete the understanding of those and more.
They should also know bits and bit logic and applying that to port registers and process states down at the small memory level of MCU boards like the Uno.
Pointers and bitwise logic are extreme power tools of C and C++. What would you do with an array of pointers to functions?
I did not think that was the topic of the tutorial at all. And it Seems to me that guarding against multiple definition is part of the general introduction to external file inclusion.
I’d vote to have everything in just the .ino and skip the .h (or do it right with an .hpp or a combo .h and .cpp)
considering that this is the "Programming Questions Forum" i've always thought the focus should be on answering the question of the OP, not necessarily teach or even explain.
It's not obvious the OP even care about programming. they may be a non-programmer, even an artist (see Explainer), and just need to make some code work.
of course, the answer may be a missing brace, "=" instead of "==" or just plane badly structured code. providing a more conventional approach. i often take the liberty of providing a "better"(?) approach which some posters appreciate while other forum members take issue with that it's beyond the understanding of a newbie
As an EE i learned many programming skills from books, many from Brian Kernighan who even explained how to implement a small scripting language in a single chapter (8, Program Development) in The Unix Programming Environment.
but i've always thought it was a sad commentary on programmers that his last book, The Practice of Programming seemed to go back to basic programming
:)) and when later on the students hit the issue they refer this as the "lollipop bug" and everyone know what this is because of the anchoring exercise.
