Happy Birthday to Claude Shannon.

Shannon is known as the “father of information theory” because of the landmark paper he published in 1948. He is also known for founding both digital computer and digital circuit design theory in 1937. Shannon received the IEEE Medal of Honor in 1966 “For his development of a mathematical theory of communication which unified and significantly advanced the state of the art.” Claude Shannon would have been 106 on the 30th of April 2022.

Shannon had lots to do with the sampling theorem.

Happy birthday, Claude Shannon!

ELMG Digital Power CTO Dr. Hamish Laird has completed Xilinx Partner technical recertification for ELMG Digital Power’s ongoing Xilinx partner program.

This ongoing commitment to capability, learning, and keeping up to date with Xilinx technology is an investment that pays dividends when we are implementing high-performance digital power controllers.

This year’s recertification covered the new Versal ACAP. This extended SoC device is powerful to the point of being daunting. As Dr. Laird says “I was suspicious of the suitability of the ACAP as a device for power control but I can now see how this device is suitable for almost every application we could ever consider.”

Xilinx Partner technical recertification – the certificate

Dr Laird continues “We are really thankful to Xilinx for our ongoing partnership program membership. The program is great and allows us access to world-leading devices, toolchains, and training. Completing this Xilinx Partner Technical recertification is always a great day in the year. The training material is really good and well worth the time and effort required.”

About Xilinx

We Are Building the
Adaptable, Intelligent World

Xilinx is the inventor of the FPGA, programmable SoCs, and now, the ACAP. Our highly flexible programmable silicon, enabled by a suite of advanced software and tools, drives rapid innovation across a wide span of industries and technologies – from consumers to cars to the cloud. Xilinx delivers the most dynamic processing technology in the industry, enabling rapid innovation with its adaptable, intelligent computing.

About ELMG Digital Power

We Provide Technology, Know-How and Products to Control, Manipulate and Measure Electrical Power.

ELMG Digital Power aims to design and build the best digital controlled power electronic systems.
By doing that we change the world for the better.

ELMG Digital Power is part of a select group of companies invited to be part of the Xilinx Partner Program. Each year ELMG people complete training in Xilinx tools and devices.

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.

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