Archive for the ‘Uncategorized’ Category

Fighting Evil in Code Comments.

Wednesday, September 15th, 2021

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.

New IEEE Senior member, Dr. Hamish Laird

Wednesday, August 18th, 2021

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.

#ieeeforlife

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

Friday, August 13th, 2021

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: https://rt21.vfairs.com/

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: https://rt21.vfairs.com/

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.

PSMA Software Firmware Reliability Improvement Report

Monday, December 2nd, 2019

Improvement of software reliability is a pressing issue in the digital control of power electronics. It is commonly reported by managers and executives in large power supply purchasing OEMs that most of the issues with power supplies are due to software problems.

Improving software quality for digital power

As part of an initiative by the Power Supply Manufacturers Association (PSMA) Reliability Committee, ELMG Digital Power provided research, examples and written material for the PSMA Software Firmware Reliability Improvement Report.

ELMG Digital Power is proud to be primary contributor to the PSMA Software / Firmware Reliability Improvement Report

Typical issues in digital power electronics

Typical issues in digital power electronics include

  • Limited modulator precision due to timer and clock speed
  • Numeric precision limits in digital filters
  • Excessive delays from limited processing power

Software quality improvement

As software quality is the result of following and implementing a repeatable process the report details how

  • Version control
  • Code standards
  • Defect tracking
  • Code reviews
  • Code inspections
  • Inspections before testing
  • Test specifications

are used to improve code quality.

How do you get the report?

Best way to get the report is to join the PSMA or you can purchase it.

Want to preview the report?

Improving Quality is the ELMG Way

We are all really proud to be part of the effort to create this report on improving the quality of software in power supplies. It fits really well with our aim to improve the performance, efficiency and quality of digital power electronics systems.

Contact us for software quality improvement

If you are interested in having us review your software code and development process contact us.

Xilinx Alliance Program Re-Certification

Thursday, July 4th, 2019

ELMG Digital Power and the Xilinx Alliance Program

ELMG Digital Power and the Xilinx Alliance Program is an ongoing, valuable and extremely valuable 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 Vivado Suite continue to allow exceptionally fast, reliable and robust development flows.  We are really pleased to continue with ELMG Digital Power’s Xilinx Alliance Program commitment and are please to be part of the Xilinx community.”

ELMG Digital Power and the Xilinx Alliance Program

Certification for ELMG Digital Power CTO, Dr Hamish Laird

Dr Laird continues

“For me this training let’s me stay capable and able to create Xilinx based power electronics controllers. Xilinx products are great and the support and capability we can provide to customers is amazing.”

Contact ELMGDigitalPower now.

ELMG Digital Power and the Xilinx Alliance Program

Xilinx Alliance Member ELMG Digital Power

Choosing you power electronics processor effectively in Digital Power Electronics Development – Free Webinar

Thursday, May 16th, 2019

Tuesday June 4 at 12 noon PDT (3pm EDT)

How do you choose your processor.

Your Digital Power Electronics Processor Choice power electronics processor is crucial to success in Digital Power. And the key to choosing in a way that doesn’t end up creating delays in the project delivery.

So what are the most important issues to consider

Processing latency

Delays in the digital processor add phase lag and so can make getting stable operation at reasonable target bandwidth. Estimating accurately the delay that is acceptable and possible with possible target processors ensures that the processor will not run out of time during the development.

How to manage the limited number of bits

The limited number of bits in a processor means that there is a trade off between precision and dynamic range. The natural instinct is often to have larger dynamic range and lower precision. Best practice is to choose the opposite. Joins us in the webinar to see why.

Timer resolution

Likewise timer precision limits the available resolution in PWM and variable frequency modulators.

ELMG Digital Power are offering you the opportunity to attend our regular webinar on Digital Power Electronics. The next webinar is

Tuesday June 4 at 12 noon PDT (3pm EDT)

This is an hour webinar on that details the accumulated ELMG Digital Power experience with processor choices for power electronics control

Join ELMG Digital Power’s regular monthly Digital Power Webinar and expand your Digital Power knowledge and expertise. 

The webinar will be hosted and presented by Dr. Hamish Laird  ELMG Digital Power’s CTO  Hamish has 25 years experience the design and implementation of varied digital control systems and IP for power electronics.

This exciting opportunity is free and includes a 15 minute Q&A session with Dr. Hamish.

Dr Hamish Laird

The webinar is scheduled for

Tuesday June 4 at 12 noon PDT (3pm EDT)

Click the link below to sign up for the webinar

http://info.elmgdigitalpower.com/choosing-your-digital-power-processor