Since I am very new to this,
could someone advise me where to find some instructions regards the proper format to type coding for a sketch.
example : where to place curly brackets,
what to enter on a given line of code
Or do you just rely on the Autoformat option of the IDE?
Thanks
Arduino programming is done with C++. A C ++ tutorial will get you started on the language and syntax. On the learning tab of this site you will find an Arduino language reference that has information about the Arduino functions and tutorials on basic Arduino programming. The IDE has many examples that show code for basic sketches. Look in the File menu for the examples. And if that is not enough Google will find hundreds if not thousands of tutorials with a search for Arduino tutorials.
Read Mr. Gammon's discussion 'Style guide' about 2/3s down.
What the heck, read/memorize the whole thing.
.
Style, like beauty ...
Im addition to Nick Gammon's guide (and apologies to him if he has covered this) use meaningful variable names for variables and functions. Meaningful names remove the need for many comments and fewer comments reduces the risk that comments don't get updated when the code is updated.
My objective when I write a program is to be able to understand it 6 months later after reading it through once. Of course I often fail at my own objective.
In my own code I find it helpful to indent comments further than the code - like this
myNewNumber = myOldNumber * 2;
// this is an indented comment
anotherNewNumber = myOldNumber + 3;
By doing it like that my eye can scan the code without being distracted by the comments
You might like to look at Planning and Implementing a Program
...R
+1 for Robin2 regarding variable names. Wikipedia covers this topic as does numerous online articles like this one.
The above being said, I am old and was schooled in the old way of using comments... often multi-line ones. I find comfort in that old style and I typically will drift into this style for my own work. If one wishes to be great at self-documenting code, they should use that style consistently. Many commercial (most) have their own best practices that are enforced.
Ray
Write the code in a way that makes sense to you. Then, use Ctrl-T in the IDE and it will reformat your code into a pretty common C style that most of us are comfortable with. We each probably have some deviation with the resulting style, but it's a good starting point.
mrburnette:
If one wishes to be great at self-documenting code, they should use that style consistently. Many commercial (most) have their own best practices that are enforced.Ray
Good point. My coders had to follow a strict coding style. If anyone found code that didn't conform in production code, the author of that code had to buy pizza for everyone after the Friday code walk-through. It didn't take long for everyone to learn the new style.
It wasn't a question of dictatorial style, rather it was a recognition that I had a small company and everyone needed to be able to read everyone else's code. People take vacations, get sick, or need personal leave and someone else needed to step in for a while and an identical coding style helped. Also, I wrote a filter that would extract the common-style function header comments, producing a document of every function we had in a project's library. That would not have been possible had a common style not been enforced.
I also geared small teams with tasks designed to take less than two weeks. They would present their code to all programmers on a Friday code walk-through. Identical coding style helped this. Also, if the team passed the walk-through, my company bought pizza for lunch and everyone got the rest of the day off. You'd be amazed how many non-members of the team facing a code walk-through were there into the wee hours of Thursday night. The cost of the pizza and time off paled compared to the insight everyone gained from working with other people's code and the camaraderie it built. Yeah, I know this wouldn't work on a large company, but it sure worked for my little company.
econjack:
Good point. My coders had to follow a strict coding style. If anyone found code that didn't conform in production code, the author of that code had to buy pizza for everyone after the Friday code walk-through. It didn't take long for everyone to learn the new style.
How fascist.
Code should be clear and readable. Good style is clear and readable. Following petty rules is
for robots, not people.
Thanks Guys
I appreciate all of your comments and links to follow up on!
MarkT:
How fascist.Code should be clear and readable. Good style is clear and readable. Following petty rules is
for robots, not people.
They weren't petty rules, they played a valuable role in the way the company worked. If one of my employees came up with a more "clear and readable" style, I would have asked the others about it at the code walk-through. If the consensus was that it represented an improvement, we would have adopted it. As long as everyone agreed and I could still produce a function document, that was fine. What didn't work was an anarchist who tried to tell everyone else that his style was better and who wouldn't follow the style everyone else used.
My guess is that you work for yourself. If you work for a company and are allowed to "do your own thing", you're lucky. With the statement that "...rules are for robots, not people" you just threw out the basic tenet for a civilized society.
Auto format doesn't do everything, like if your opening curly brackets are on their own line or following the if/function/etc, that 'style' choice is maintained
INTP:
Auto format doesn't do everything, like if your opening curly brackets are on their own line or following the if/function/etc, that 'style' choice is maintained
Very true. Still, Ctrl-T does often produce a more easily read program than those often presented here. While I prefer the K&R brace style, at least the reformat makes it easier to read code that doesn't have a style.
INTP:
Auto format doesn't do everything, like if your opening curly brackets are on their own line or following the if/function/etc, that 'style' choice is maintained
You can change the way that Auto Format works by changing the formatter.conf file