The ELMG Blog

Fighting Evil in Code Comments.

So I have become a superhero – I am fighting evil in code comments. For those of you that know me, I always talk about myself as a power electronics hardware and control person. And since about 1997 I have designed control systems that for the most part have been implemented in code of some kind. If you had told me back in 1991 when I finished my Masters that I’d end up being a software person I’d have told you that this was so unlikely that I could not see it happening. And now I spend the balance of my time looking at code. Typically it is VHDL code, Verilog Code, C code or Python code and sometimes I look at C++ code. When I look at this code I am trying to work out what the code does, usually because the code is not doing what it is meant to. Whether it is the pulse or PWM generator code for a DC to DC converter or the repetitive filter necessary to minimise the harmonic content in a UPS voltage waveform it always comes down to looking at the code. So how do you know if the comments are evil? How do you go about fighting evil in your code. Some comments on comments.

The use of requirements, design records, interface specifications, verification test plans, code testing tools, unit testing, version control, automated documentation extraction like doxygen, and code reviews does not ever seem to ever be enough to get the code to do what it needs to.

And then there are the comments that I see in the code. This is the most amazingly varied and strange part of the code review experience. There seems to be no agreement on

  • Why comments are in the code?
  • What goes in a comment?
  • Who the comment is for?
  • Why the comment did not get maintained when the code was changed?

The answer to the last question is the reason that 15% (from ELMG Digital Power Polls) of everyone who codes insists that they will not ever use comments. (This is my present opinion and most frequent practice for VHDL and Verilog)

The answer to the other three questions causes discussions of a vehemence that only software people can bring to an argument.

I have a collection of articles and opinions that are from some of the best in the embedded software development space. And I have a collection of articles and opinions that are from some of the best in the software space.

The article that this post is named for is from Michael Sorens. He is worth reading for all good advice about things software development.

This is the article – it is a long read and is quite confronting to software people.

Here are a few excerpts.

What’s Wrong with Comments

The problems with comments are many and varied:

  • Over time, and not intentionally, comments can lie, so can lead to misinterpreting the code if you happen to believe the comment.
  • Writing comments takes time, more so if you choose a commenting style that requires a lot of time to look pretty, so strive for simplicity.
  • Comments make a file longer and can often introduce unnecessary clutter, thus requiring more time to read. Steve Smith, in When to Comment Your Code, reminded me of a very relevant quote from that classic tome on writing, The Elements of Style, and it applies just as validly to code: “Omit needless words. Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.”
  • Comments often attempt to explain what or how, which tends to merely repeat the code; comments should always address the why.
  • In maintaining code you also have to maintain any associated comments too, thus requiring more effort.
  • Writing comments that are clear rather than cryptic is hard. I recent comment (pun intended) I read on this was enlightening: if the code was written in a confusing manner why would you expect the code author to suddenly be able to write comments about it clearly?

As I have said here, and you may have seen elsewhere, comments frequently lie. What does that really mean? Here’s an example from Dietrich’s article along with his commentary:

// Returns x + y or, if x or y is less than zero, throws an exception
public int Add(int x, int y)
    return x + y;

What happened here? When you put on your code archaeology hat, you’ll probably conclude that a guard condition once existed. Someone deleted that guard condition but didn’t think to update the now-nonsensical comment. Oops.

Oops, indeed! Comments, unlike code, are not checked at edit time (unless you’re writing doc-comments, discussed later) or at compile-time or at runtime. You cannot lint your comments. You cannot unit test your comments. In other words, there are no safeguards. Thus, whether you are dealing with good comments or evil comments, you should strive to minimize them so they do not become stale or downright misleading, as in the above example.

Many developers do not like to write documentation of any sort, and that includes comments. (For a good list of excuses reasons, see Why programmers don’t comment their code. But commenting too little (or not at all) is just as bad as commenting too much. As I and many others have stated, comments are often necessary but try to keep them to a minimum.

How Evil is your comment? Fighting evil in code comments.

In ELMG Digital Power Polls most people answer that most of their comments are a description of what or how the code does or works (56%) and repeating the code (75%) and no one (0%) respond that their comments are why the code is the way it is. And this is pretty much exactly the opposite of good or best practice using the “evil scale” in the diagram below.

Fighting evil in code comments
Fighting evil in code comments

Check out the article. It is worth a look to make comments more mindful and less evil.

Git made easy with cats

If you

  • spend time working with git
  • deal with people who use git or are trying to use git
  • need to be able to show people how git works
  • and like cats

then these are great explanations from @girlie_mac – Tomomi Imura whose original blog post is at

Git with cats because everyone loves cats.

New IEEE Senior member, Dr. Hamish Laird

Thanks to all that have helped along the way. Professors, colleagues, and all my family. I got this from IEEE today

“It is a great pleasure to congratulate you on your elevation to the grade of IEEE Senior member. IEEE Senior Membership is an honor bestowed only to those who have made significant contributions to the profession.” 

After being a member of the IEEE for 24 years I finally decided to apply for senior membership. Thanks to those who were referees for me and for giving positive reports. Big shout out to all my University Professors including Professor. Richard Duke, Dr. Simon Round, Professor Jos. Arrillaga, and Professor Alan Wood. Thanks also to all the people who have supported me through the good times and bad.

Thanks also for the good wishes from colleagues around the world. Stay safe and thanks.

Join the IEEE. Click below.


About the IEEE

IEEE is the world’s largest technical professional organization dedicated to advancing technology for the benefit of humanity.

Mission statement

IEEE’s core purpose is to foster technological innovation and excellence for the benefit of humanity.

Vision statement

IEEE will be essential to the global technical community and to technical professionals everywhere and be universally recognized for the contributions of technology and of technical professionals in improving global conditions.

Validation of Power Electronic Industrial Applications through HIL

Don’t miss ELMG Digital Power’s own Dr. Hamish Laird contributing to the OPAL-RT panel discussion: Validation of Power Electronics through HIL. In this panel, renowned experts are going to share their vision of the future of the power electronics industry.

Panelists are:
Hamish Laird, Chief Technology Officer at ELMG Digital Power,
Geraldo Nojima, MV Power Conversion Chief Technologist at Eaton,
Mathieu Giroux, Head of Product Engineering and Quality at ABB,
Alex Q. Huang, Chair Professor at The University of Texas at Austin
Ilknur Colak, Head of Power Electronics R&D at Maschinenfabrik Reinhausen, and
François Tempez, Business Development at OPAL-RT TECHNOLOGIES

Register now:

Validation of Power Electronics through HIL in Industrial Applications
Dr. Hamish Laird on the expert panel at RT21

Validation of Power Electronics with HIL is one tool to deliver better power electronics faster and with higher quality.

Come join the expert panel to see what the pitfalls and advantages of HIL are.

Register now:

About HIL

Hardware in the loop (HIL) is a testing approach where parts of the power electronic test system are the actual, final, will-be-used in the field hardware. Typically this can be the power electronics controller. The HIL unit then simulates the power converter in real-time. This setup allows testing the real controller running the real software with a simulated power converter. Errors in the control don’t explode the power converter or cause long project delays. Electrical safety is also simplified when the high voltage power converter is simulated rather than running with a high current. The key question with HIL is around the accuracy of the power converter simulation.

OPAL-RT make real-time (RT) simulators for power electronics and power systems.

ELMG Digital Power has no formal partenership with OPAL-RT. We often help our customers with all types of real-time simulation issues.

Contact ELMG Digital Power for real-time power electronics help.

May 18 Webinar – Basics of Digital Control of Power Electronics

Our webinar series is back! Grab your lunch or a coffee and join us for this free webinar on the basics of digital control of power electronics.

From the comfort of your own desk you can join ELMG Digital Power for a free webinar to expand your knowledge and expertise about the advantages that digital electronics provides including:

* Flexibility
* Configurability
* Re-tuning the loop for component variation such as Electrolytic capacitor freeze out at low temperatures
* Management of the non-linearity of the converter
* Self-measurement of the loop response in closed and open-loop

and learn about the three key basics of digital control of power electronics these being

1. Limited number of bits.

2. Power converter characteristics including non-linearity

3. Limited PWM timer precision

This webinar will be hosted and presented by Dr. Hamish Laird, ELMG Digital Power’s CTO and a Principal FPGA and Power Electronics Engineer. Hamish has considerable experience in the design and implementation of varied digital control systems and IP for power electronics on FPGA platforms.

The webinar on Basics of Digital Control of Power Electronics: Where to start and what is important will be held May 18, 2021, at 12 Noon PDT on Zoom.

Spaces are limited.  

See you at the webinar.

Click here to register

Xilinx Alliance Program Engineer Re-Certification 2020

ELMG Digital Power Engineers and the Xilinx Alliance Program

ELMG Digital Power Engineers and the Xilinx Alliance Program form an ongoing, valuable, and extremely productive partnership.

When asked about this ELMG Digital Power CTO,  Dr. Laird said

“Maintaining ELMG Digital Power’s commitment to providing exceptional service and products is our key uniqueness. To this end we are pleased to continue in the Xilinx Alliance Program membership.  We see great things happening with Xilinx All Programmable FPGAs and Zynq SoCs, UltraScale devices and the Spartan7.

It is great to see the capability of the Xilinx tools like Vitis and the Vivado Suite continue to allow exceptionally fast, reliable and robust development flows.  We are really pleased to support engineers to maintain competance and capability with Xilinx tools and devices.”

ELMG Digital Power Engineers and the Xilinx Alliance Program

Continuing Training with Xilinx Tools and Devices at ELMG Digital Power

Dr Laird continues

“As always this training opportunity let’s me stay capable and able to create Xilinx based power electronics controllers. Learning about the new improved HLS and Vitis tools is an invaluable capability to offer ELMG Digital Power Customers.”

Contact ELMGDigitalPower now.

ELMG Digital Power and the Xilinx Alliance Program

Xilinx Alliance Member ELMG Digital Power

About the Xilinx Partner Program

The Xilinx Partner Program is a worldwide ecosystem of qualified companies who offer Acceleration solutions, IP cores, Design Services, and Board development and production. Ecosystem Partners help system designers in the rapid integration of Xilinx FPGAs, SoCs, 3DICs, intellectual property, and software-defined solutions. They offer proven products and expert design support from chip level to full turnkey product development, which accelerate time to production of complex electronic systems.

ELMG Xilinx Alliance Partner Listing