Jack Ganssle's Blog This is Jack's outlet for thoughts about designing and programming embedded systems. It's a complement to my bi-weekly newsletter The Embedded Muse. Contact me at jack@ganssle.com. I'm an old-timer engineer who still finds the field endlessly fascinating (bio). |
How I write Code
December 16, 2019
"If you think good design is expensive, what about the cost of bad design?"
I believe strongly in solid design of all engineering artifacts. Unless it's something trivial, I'll start with at least a rough block diagram before creating a schematic. For a technical document the table of contents comes first. In both cases it's obvious that these are usually rough and tend to change as the schematic or document is created. But they give a sense of direction that guides the formation of the artifact.
Ditto for code.
And ditto for the details of writing individual functions.
First, I write the header block with a description of the function's function, and passed parameters. For a trivial procedure, that might be the only commenting needed. For instance:
/************************************************** Function to toggle the debugging pins. Inputs: - Which trigger (0 or 1) to pulse - Time (in usec) to assert the pin Coded 01/14/2017 by JGG **************************************************/
Then it's easy to fill in the C:
void trigger(int pin, int time_usec) { switch(pin) { case 0: trigger0 = 1; wait_us(time_usec); trigger0 = 0; break; case 1: trigger1 = 1; wait_us(time_usec); trigger1 = 0; } }
A bit more complex function starts the same way, with a complete header block:
/********************************************************************** Function to read the analog input selected by the muxes. It also corrects the reading by applying the scaling factor determined by a prior read of the reference voltage. The correction is needed as experience with this board shows the A/D is a bit sensitive to temperature. Vref, from an AD780, is very stable and runs through the same muxes and ADC.
If the battery is VREF, it reads the reference and recomputes the scale factor. The scale factor is an average of AVG_REF reads of the reference voltage normalized to the known reference voltage (VREF_NOMINAL). Inputs: - Battery desired (from battery enum) - Which voltage of that battery to read (from which_voltage enum) Returns: - Analog voltage Coded 01/16/2013 by JGG **********************************************************************/
Then, I write the function declaration, and the most important comments that will go in that function:
float analog_read(battery batt, which_voltage volt) { // Set analog mux to desired batt and voltage // If VREF, read the AD780 and recompute scale factor // Note: Normalize the scale to ADC_REF, the ADC // reference voltage
I'll present my Better Firmware Faster seminar in Melbourne, Australia February 20. All are invited. More info here. |
Now it's a trivial matter to fill in the code:
float analog_read(battery batt, which_voltage volt) { int i; float result = 0; analog_select(batt, volt); // Set analog mux to desired batt and voltage if(batt == VREF) // If VREF, read the AD780 and recompute scale factor { scale = 0.0; for(i = 0; i < AVG_REF; i++)scale = scale + adc.read(); scale = scale * ADC_REF / float(AVG_REF);// Note: Normalize the scale to ADC_REF, the ADC // reference voltage scale = VREF_NOMINAL / scale; } else // If not VREF, read & average the ADC and scale result { for(i = 0; i < AVG_OTHER; i++)result = result + adc.read(); result = result * scale * ADC_REF / float(AVG_OTHER); } return result; }
By writing the comments first I've designed the structure of the function. Design is the hard part, and these details, if wrong, will doom the project.
Code is merely an implementation detail.
(This is a pretty simple example; more complex code benefits more from designing first).
Some developers think it's possible to write self-documenting code. As one who reverse-engineers an awful lot of the stuff, I have never seen a non-trivial project that is truly self-documenting. A future maintainer may have no idea what the code is trying to accomplish. Good comments greatly streamline gleaning information from what might be complex code.
Feel free to email me with comments.
Back to Jack's blog index page.
If you'd like to post a comment without logging in, click in the "Name" box under "Or sign up with Disqus" and click on "I'd rather post as a guest."
Recent blog postings:
- Non Compos Mentis - Thoughts on dementia.
- Solution to the Automotive Chip Shortage - why use an MCU when a Core I7 would work?
- The WIRECARE - A nice circuit tester
- Marvelous Magnetic Machines - A cool book about making motors
- Over-Reliance on GPS - It's a great system but is a single point of failure
- Spies in Our Email - Email abuse from our trusted friends
- A Canticle for Leibowitz - One of my favorite books.
- A 72123 beats per minute heart rate - Is it possible?
- Networking Did Not Start With The IoT! - Despite what the marketing folks claim
- In-Circuit Emulators - Does anyone remember ICEs?
- My GP-8E Computer - About my first (working!) computer
- Humility - On The Death of Expertise and what this means for engineering
- On Checklists - Relying on memory is a fool's errand. Effective people use checklists.
- Why Does Software Cost So Much? - An exploration of this nagging question.
- Is the Future All Linux and Raspberry Pi? - Will we stop slinging bits and diddling registers?
- Will Coronavirus Spell the End of Open Offices - How can we continue to work in these sorts of conditions?
- Problems in Ramping Up Ventilator Production - It's not as easy as some think.
- Lessons from a Failure - what we can learn when a car wash goes wrong.
- Life in the Time of Coronavirus - how are you faring?
- Superintelligence - A review of Nick Bostrom's book on AI.
- A Lack of Forethought - Y2K redux
- How Projects Get Out of Control - Think requirements churn is only for software?
- 2019's Most Important Lesson. The 737 Max disasters should teach us one lesson.
- On Retiring - It's not quite that time, but slowing down makes sense. For me.
- On Discipline - The one thing I think many teams need...
- Data Seems to Have No Value - At least, that's the way people treat it.
- Apollo 11 and Navigation - In 1969 the astronauts used a sextant. Some of us still do.
- Definitions Part 2 - More fun definitions of embedded systems terms.
- Definitions - A list of (funny) definitions of embedded systems terms.
- On Meta-Politics - Where has thoughtful discourse gone?
- Millennials and Tools - It seems that many millennials are unable to fix anything.
- Crappy Tech Journalism - The trade press is suffering from so much cost-cutting that it does a poor job of educating engineers.
- Tech and Us - I worry that our technology is more than our human nature can manage.
- On Cataracts - Cataract surgery isn't as awful as it sounds.
- Can AI Replace Firmware - A thought: instead of writing code, is the future training AIs?
- Customer non-Support - How to tick off your customers in one easy lesson.
- Learn to Code in 3 Weeks! - Firmware is not simply about coding.
- We Shoot For The Moon - a new and interesting book about the Apollo moon program.
- On Expert Witness Work - Expert work is fascinating but can be quite the hassle.
- Married To The Team - Working in a team is a lot like marriage.
- Will We Ever Get Quantum Computers - Despite the hype, some feel quantum computing may never be practical.
- Apollo 11, The Movie - A review of a great new movie.
- Goto Considered Necessary - Edsger Dijkstra recants on his seminal paper
- GPS Will Fail - In April GPS will have its own Y2K problem. Unbelievable.
- LIDAR in Cars - Really? - Maybe there are better ideas.
- Why Did You Become an Engineer? - This is the best career ever.
- Software Process Improvement for Firmware - What goes on in an SPI audit?
- 50 Years of Ham Radio - 2019 marks 50 years of ham radio for me.
- Medical Device Lawsuits - They're on the rise, and firmware is part of the problem.
- A retrospective on 2018 - My marketing data for 2018, including web traffic and TEM information.
- Remembering Circuit Theory - Electronics is fun, and reviewing a textbook is pretty interesting.
- R vs D - Too many of us conflate research and development
- Engineer or Scientist? - Which are you? John Q. Public has a hard time telling the difference.
- A New, Low-Tech, Use for Computers - I never would have imagined this use for computers.
- NASA's Lost Software Engineering Lessons - Lessons learned, lessons lost.
- The Cost of Firmware - A Scary Story! - A hallowean story to terrify.
- A Review of First Man, the Movie - The book was great. The movie? Nope.
- A Review of The Overstory - One of the most remarkable novels I've read in a long time.
- What I Learned About Successful Consulting - Lessons learned about successful consulting.
- Low Power Mischief - Ultra-low power systems are trickier to design than most realize.
- Thoughts on Firmware Seminars - Better Firmware Faster resonates with a lot of people.
- On Evil - The Internet has brought the worst out in many.
- My Toothbrush has Modes - What! A lousy toothbrush has a UI?
- Review of SUNBURST and LUMINARY: An Apollo Memoir - A good book about the LM's code.
- Fun With Transmission Lines - Generating a step with no electronics.
- On N-Version Programming - Can we improve reliability through redundancy? Maybe not.
- On USB v. Bench Scopes - USB scopes are nice, but I'll stick with bench models.