Dumb Questions From a Not-dumb Newbie

I'm an electrical engineer who's done practically no electronics in his 20 year career, so I know a lot and nothing at the same time. I received an Uno starter kit to try to get my chops back, and I have completed my first practice project. So here are the dumb newbie questions:

  • Is there anyplace that project descriptions and code for this sort of thing are welcome? That is, does anybody care to see my virtually pointless practice stuff? I'd certainly like to get feedback if anybody has any. I would have thought these fora would have such a place, but I don't see what looks like one.
  • Is there a community standard (official or not) for an opening comment block? If I share my stuff, I'd like to do it right.

There have been many programs put in the forum for commenting on. This helps newbies learn better ways of doing things.

There will be very blunt comments from some members. Do not take it personally! There are some that have been programming for a long time and may forget that there are newbies asking for assistance or programming tips, that have not been programming for long.

Official methods of opening comments don't seem to exist as far as I know. I prefer to start with the program name and version then give a description of what the program is supposed to do.

I also put comments on what still has to be done and any testing still required to make it work as intended.

This makes it easy to come back at a later date and know what has to be done.

Weedpharma

Welcome.

If you follow the threads for a while you will get a good feel how things happen here.
Explore the different areas on this site.

Ignore comments that you should ignore. :wink:

When you get some time look through Nick Gammon's web site:

Have fun re-learning!
.

jqavins:
I'm an electrical engineer who's done practically no electronics in his 20 year career, so I know a lot and nothing at the same time. I received an Uno starter kit to try to get my chops back, and I have completed my first practice project. So here are the dumb newbie questions:

  • Is there anyplace that project descriptions and code for this sort of thing are welcome? That is, does anybody care to see my virtually pointless practice stuff? I'd certainly like to get feedback if anybody has any. I would have thought these fora would have such a place, but I don't see what looks like one.
  • Is there a community standard (official or not) for an opening comment block? If I share my stuff, I'd like to do it right.

Hi Joe,

This may be one of the comments Larry said to ignore, but I'm gonna make it anyway.

The answer to 1 is "No." We do not need to see your first sketches and trial programs. We've made mistakes and seen others make them as well. Learning microcontroller programming is a process.

This place works by being part of that process. Some folks here are experts in their - microcontroller/microprocessor directed - field. Read the forum for a while, and you will realize who those folks are. Others post good questions. A good question is one that can be answered using the information contained in the question, AND the knowledge of the "gurus" who answer the question. A post by one of our moderators, Nick Gammon, shows a good way to post a question. The more information provided, the better, is the general rule.

Your question 2 allows you more discretion. If you believe your post may be of interest, by all means post it. The folks here may, or may not, agree. My recommendation is to take a chance and post it up!

I am inclined to the same view as @ChrisTenone (including his comment about ignoring me).

With regard to your question 1, if what you have in mind is to write a tutorial that you believe would be useful for other newbies feel free to do so, but keep in mind that there are already many Arduino tutorials on the internet.

One of the risks you run, with a tutorial that is written by a newbie, is recommending "bad habits" such as using delay() or trying to read more characters with Serial.read() than are known to be in the input buffer. That sort of thing will draw a lot of adverse comment.

...R

Robin2:
I am inclined to the same view as @ChrisTenone (including his comment about ignoring me).

With regard to your question 1, if what you have in mind is to write a tutorial that you believe would be useful for other newbies feel free to do so, but keep in mind that there are already many Arduino tutorials on the internet.

One of the risks you run, with a tutorial that is written by a newbie, is recommending "bad habits" such as using delay() or trying to read more characters with Serial.read() than are known to be in the input buffer. That sort of thing will draw a lot of adverse comment.

...R

Well, since no one seems to be offering a different opinion, I'll go with that.

For the record, no I'm not thinking of writing a tutorial; as a newbie, the last thing I'd want to read is a tutorial written by a newbie like me. No, what I was hoping to find include things like those bad habits. I have used delay(), as do some of the example sketches in the Getting Started book. If there's a reason that's a bad idea I'd like to know, but I would never have thought to ask about delay() specifically. It's just that sort of general critique that I was after.

The other side of the coin is that, just maybe, I've done something differently from the norm that someone might be interested to see. Without knowing the norms, I couldn't say specifically what.

Anyway, if this forum isn't the place for that then I will not pursue the matter further.

The long gap between your question and your response leads me to wonder if you have read many of the Threads on the Forum. If you read the Forum regularly for a week or two you will get a good feel for what is usual.

the last thing I'd want to read is a tutorial written by a newbie like me

That is not at all a stupid idea. Once you cease being a newbie it can be very difficult to remember what it was that caused you all the problems. And others may very well benefit from some notes about your learning process.

...R

Robin2:
The long gap between your question and your response leads me to wonder if you have read many of the Threads on the Forum. If you read the Forum regularly for a week or two you will get a good feel for what is usual.
That is not at all a stupid idea. Once you cease being a newbie it can be very difficult to remember what it was that caused you all the problems. And others may very well benefit from some notes about your learning process.

...R

Yes, I've been away from the forum, tinkering with my next project, reading various reference material, and looking for a job. What I've learned so far about how things work on this forum is that if one's question is deemed too general, the answer is likely to be "Go read a few hundred posts at random."

jqavins:
... if one's question is deemed too general, the answer is likely to be "Go read a few hundred posts at random."

Now we have a distilled version of that question with the "useful threads" thread.

jqavins:
What I've learned so far about how things work on this forum is that if one's question is deemed too general, the answer is likely to be "Go read a few hundred posts at random."

That is definitely not what I tried to say. I thought I had said that familiarity with the sorts of things that are discussed on the Forum and the depth and breadth of that discussion will help you to judge how to develop your own contribution to the Forum.

You did not start this Thread with a question seeking advice about an Arduino problem. You started it by asking how you could usefully share your learning experience with others. My comments should be seen in that context.

...R

jqavins:
Is there anyplace that project descriptions and code for this sort of thing are welcome? That is, does anybody care to see my virtually pointless practice stuff? I'd certainly like to get feedback if anybody has any. I would have thought these fora would have such a place, but I don't see what looks like one.

My response to this question would be to only post your code (or project) if you have a question regarding something; that is, if you are stuck, or are looking for a better (more efficient or something) solution, or something else of that nature. In those cases, we like to see the full code (if possible - sometimes the full code can be unwieldy to post - more on this later) and a schematic of your circuit; sometimes pictures of your project can help as well (indeed - if the problem turns out that you wired it wrong, then having both clear and large pictures, with the schematic - can be doubly helpful towards a solution). Also - remember to use the code tags when you do post your code.

If you just want a way to document your progress, perhaps to keep track of code or such - then a very good way to do so would be to install and learn to use Git:

https://git-scm.com/

To that end, setting up a github account will allow you to publicly share your code and other parts of your projects as you go (which can help especially if your code is very large):

I should note here that while the basics of git and github are fairly simple, the system itself can be used in quite complex ways. Also - while there are many options for GUI based access (if you are on Windows, for instance, TortiseGit is one of the best, SourceTree is another), learning to use git from the command line is something to explore and know as well (because sometimes, you can find yourself in a situation where only the command line can fix it).

The point of using Git (and Github) is to allow you to not only share your code easily, but to also have a history of your changes (this is called version control, if you're not familiar) - that way, if you mess up, you have a very easy way to go back. You can also take a version of your code, and create one or more "branches" - which you can experiment with different changes (this also allows multiple people to work on the same code), then you can merge the changes together, get rid of them, or merge them back to the master (main) branch of code.

Most of the time, for a single user, all you need to know is how to set up a repo, push (upload) the code, clone or check-out the code, add or delete changes, and commit the changes (with a comment - always update this with a valid comment, so you know what and why you did something). Also - commit early, commit often - this can help you if you need to revert changes back to what they were "earlier".

Now - you may say to yourself "I don't need to do all of that - I can just save a file with a date, make backups, etc" - and you'd be wrong. Believe me, once you experience and understand software version control, you will wonder how you ever got along without it.

Another potential useful way to help track your projects and progress is via Hackaday.io (https://hackaday.io) - you can think of it as a journal for your projects. Realize, though, that you are at the mercy of another company - if they go belly up or sell out, or change management or any number of other possibilities (ask users of Let's Make Robots! about that if you want a horror story); it's free (like Github - but at least with Git you always have a local copy of everything), but it isn't as "yours" as using your own hosted website or something (which is always the best option, IMHO, if you know how and can afford it).

Other things you could do would be to use Dropbox, Google Drive (and other Google Apps), or some other similar service - to at least hold your code, help keep track of stuff, share with others, etc (but note - none of these are substitutes for software version control systems like Git).

jqavins:
Is there a community standard (official or not) for an opening comment block? If I share my stuff, I'd like to do it right.

A community standard? Nope, not that I know of. But are there commenting standards? You betcha!

For C/C++ that standard would be to use Doxygen commenting blocks:

http://www.stack.nl/~dimitri/doxygen/index.html

Why?

Well - if doxygen commenting is used correctly and consistently (both are key, mind you!) - you can then run your code through doxygen, and generate documentation about your code from the comments, functions, etc - and have a map of everything to enable you (and others!) to understand the code better (now, and in the future - for maintenance).

Here is a somewhat complex code example (using QT-style commenting blocks - note that there are multiple styles you can use; whatever you do, select one and only one, and use it consistently - don't mix styles!):

http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#docexamples

And here is the generated (by doxygen) html output:

http://www.stack.nl/~dimitri/doxygen/manual/examples/qtstyle/html/class_test.html

While this example is a bit contrived, and may not be easy to follow, it should be apparent how such a system can help you with future maintenance and understanding (as well as help others if collaborating on a project). Believe me, you will forget what your code does and how it works; having useful documentation is paramount. I should note that it can't replace (and shouldn't) creating self-documenting code in the first place (by using consistent variable, constant, class, and function naming conventions) - but it is an important part.

Also note that in many cases, doxygen-style comment blocks can be interpreted by your IDE (if you decide to go beyond the Arduino IDE, and use something like Eclipse or NetBeans) for code hinting and completion (where as you type a function name, for instance, the IDE will show you what arguments and types are passed, and maybe a comment detailing what the function does, etc).

Finally - I know you're a newbie to all of this - and maybe the above seems like it's too much, too soon. Perhaps it is. Even so, take a look at all of it. Do your own research into what I've suggested. Implement the parts you can understand as you are able to. Even if it is just the commenting, or the version control, or proper naming conventions - whatever piece, it will ultimately help you in the future. Above all (and I tried to stress this) - be consistent with your usage. Be consistent with your coding style. Use consistent formatting and indentation and spacing. Consistency is key to all of this; it's the key to organization and maintenance, period.

Good luck, and I hope this helps in some manner.

:slight_smile:

Robin2:
That is definitely not what I tried to say. I thought I had said that familiarity with the sorts of things that are discussed on the Forum and the depth and breadth of that discussion will help you to judge how to develop your own contribution to the Forum.

You did not start this Thread with a question seeking advice about an Arduino problem. You started it by asking how you could usefully share your learning experience with others. My comments should be seen in that context.

There has obviously been a misunderstanding, and for my part in it I apologize. I started the thread by trying to ask "Is there a particular subforum where posts (like this or that) are appropriate?" A simple "No" would have been fine, as would "Yes, try (such or other) subforum." I did get a couple of simple "No" responses, and I seemed to also get, and perhaps I misunderstood, "Read the whole forum for a couple of weeks and you'll find out." If I have indeed misunderstood, then apologize for getting my back up.

jqavins:
I did get a couple of simple "No" responses, and I seemed to also get, and perhaps I misunderstood, "Read the whole forum for a couple of weeks and you'll find out."

A lot of questions are asked on the Forum (and everywhere else, no doubt) where the questioner thinks there is a simple YES/NO answer when in fact there is not.

I remain of the view that familiarity with the Forum (by reading it) will help anyone to formulate their questions better, to understand what goes where and to understand what is and is not likely to be welcome or useful.

The few tutorials that I have contributed were created so that I do not have to keep answering the same questions over and over.

...R

How many tutorials should I read before I post a question? Or is that in one of the tutorials too

It seems many people don't read anything at all before posting a question. Just jump right in, answer questions you can help with and ask questions you need help with. It looks like you're already doing that, so you're not such a newbie after all...

jqavins:
How many tutorials should I read before I post a question?

I think you are just being deliberately obtuse now.

...R