In this article, I touch on coding style, coding standards and philosophy. To paraphrase Robert Pirsig from “Zen and the Art of Motorcycle Maintenance”, this article is not really about Zen and does not tell you how to maintain firmware (or software). However, if you follow my advice, you will be on the path to coding nirvana. And you will bring great joy and enlightenment to the world.
Aspire to create a work of art and beauty with every piece of code you write. Remember that firmware lives for ever. Long after the developer has left for another job (or moved to another position) the firmware for the project lives on. I have been an Embedded Systems Consultant for over 25 years. In that time, I have worked on, ported, added to, or rewritten, firmware from dozens of different developers. Some has been beautiful, creative and inspiring. Some has been atrocious and depressing. That code you left behind bears your name. You should strive to leave behind a software legacy that will impress others with the professionalism and beauty of the art you put into developing it.
When you design code, always think of your audience. Firmware and its included documentation is not written for the developer or even the end user. True, the user cares about how well the product works, how easy it is to use, and how the product makes him feel (i.e. this is fun to use), rather than how efficient your interrupt structure is or how elegant and meticulous your coding style is. The next developer who inherits your project certainly will care. You can make her life easy (and she will marvel over your abilities as she works on the code) or you can make her life miserable. You should always write you code with that audience, the next developer who will work with your code, in mind. You want to impress to him with the simplicity, elegance, the robustness of your work. Make your firmware a thing of beauty to read. Impress others (through the use of embedded comments and documentation) with how much thought you put into the design. Show them how much time you put into making it easy to maintain.
Make sure your work is easy to follow. Comment all of your functions. Explain any tricks or non-conventional coding with comments that explain your thinking. Even it is obvious to you, it may not be to the next person. I have never complained that someone documented their work too thoroughly. Strive for simplicity. As Albert Einstein said, “Everything should be made as simple as possible, but no simpler”.
Obscure coding does not impress me. I am genuinely impressed by people who can create simple, understandable and robust solutions to complex problems. Experienced programmers understand that the system requirements will change and anticipate this by the flexibility of their programming style. Design your firmware so it easy to change and grow. Strive to create something that can stand as a teaching tool for new engineers and programmers. They will look at your code and learn from your professionalism and experience. I still learn tips and techniques from the more artistic firmware I have worked with and they become part of my repertoire.
Documentation and code comments are not written for you or your manager. Don’t think of them as drudgery. They are your legacy. Your firmware is your work of art that you leave to history. This is your chance to impress future generations of developers with your ingenuity, your creativity and your professionalism. It will build your reputation and the force will be with you. And it will make the next persons job a more pleasant experience.
Bob Weiman (TheOracle) is a Consultant designing Real-Time Embedded Systems for Medical, Commercial, and Robotics applications. He is the President of Oracle Engineering Inc. (www.AskTheOracle.com).