SparkFun Forums 

Where electronics enthusiasts find answers.

For the discussion of Arduino related topics.
By rgsparber
I have sifted through a lot of code this summer as I tried to debug my project. In most cases the code was cryptically commented. In some cases there were no comments at all or silly ones like A = B; //A equals B.

In many cases programmers had done clever things including playing at the bit level to get the number of lines of code as low as possible. I know there are cases where memory and/or real time is scarce so these techniques are essential. Interfacing directly with hardware registers also demands it. But it appears to me to be more of a badge of honor.

In my humble opinion, most of the "job" should be clear comments. Having a few paragraphs at the top of the file is also essential. This may include hardware details and key words for a web search. Yes, it takes more time, but the software can then live on as elements of the code evolve. No need for others (or even you) to throw it all out because of a hardware change and the difficulty of understanding it. The user can learn enough from the comments to make the update.

Secondly, I'm a big fan of making the code readable by the user. The computer certainly doesn't care how clever you are. This might be as simple as typing A = A + 1; rather than ++A;. They do the same thing (I think) but the former is easer for a newbie to understand. Make it too hard on a newbie and they will just give up. That is always a tragic loss.

I've also seen labels like aB234 which leave me cold. But give me a label like "WaitUntilTheFlowInputGoesHigh" and I've at least got a fighting chance. The same goes for constants and variable names. Using copy and paste means you never write any of these long strings twice and you never get a compiler error because of a typo.

I have worked with gifted programmers at Bell Labs who said you should throw out the code when it becomes to bound up in patches. This is only possible if the intent of the code has been made crystal clear. With a high quality description of the code, a person can generate new, clean code quickly. That is often much faster than trying to thread through yet another patch or new feature.
By lyndon
Most of the really bad embedded code I've seen was written by EE's. It tends to be functional and terse, but difficult to extend or inspect for defects. Programmers with a mostly software background may write bloated embedded software, but at least it tends to be readable and use good practices. Considering that software spends most of its life cycle in the Maintenance phase, this approach leads to better product.

One of my favorite quotes is:
Programs must be written for people to read, and only incidentally for machines to execute.
Abelson & Sussman, "Structure and Interpretation of Computer Programs"
Truer words were never spoken!