User Interface

What is the user interface if you are writing C code?

As people who have worked with me know, I am a fanatic (I suppose evangelist and fanatic are synonyms) for source code documentation. In all the time that I evangelized, I do not think that I ever mentioned header files.

And it is in the header file that the user interface of a C module resides.

I recently "shipped" some re-factored code to one of our teams. I shipped a second version after about a week. The revised version. changed the behaviour to make it more in line with what would be expected behaviour in the real world. Prompt came the response that no change was noticed in the files.

Going through the .c files, to locate the changes would have been difficult. WinDiff of course would have showed the difference. But it would still be confusing. What was required of my customer was to go thru the .h files. There was only one .h file that was modified. In that the signature of just one function was altered. The comments in the .h file explained the WHAT and the WHY of the change.

Unfortunately, header files are not viewed as the user interface. It should contain all the information required for the" customer" of module to use the module. The "customer" should not have to go thru the .c file. That is for maintainers.

Was I blameless? No. I missed out on a standard practice - a Change Log.

A super set of my experience, described above, is described in API Documentation.

Test Driven Development

For the past few months I have had to write C code. As some readers of this blog would know, for the past decade I have been preaching, or to use a more polite term - evangelizing, a great deal about software process and about coding practices. All of what I preached was from books that I read. What I read had enlightened me as to the mistakes I had when I was coding over the preceding decade.

The code has to be in C. I wanted to do test driven development. When I had tried to introduce unit testing in our compiler work at acmet, a major problem was the non-availability of a suitable C unit testing tool. This time around I came across the book Test Driven Development for Embedded C. It describes the use of CppUTest. I have gone through about half the book. That is sufficient for my present requirement. All the code that I am now writing is test driven.

A few weeks ago, I had to provide code for a small problem posed by one of our development teams. I found refactoring my code to create the needed modules much less of a problem than I had imagined. I could not have done it quite that easily had I not had the units tests. The discipline of TDD I found leads to far easier and better modularization. I could with full confidence hand over the modules to the concerned team.

For those doing embedded systems programming in C, I strongly recommend adopting the methods described in the book

TDD & JIT

A while back (actually quite a while back :-) I did a couple of posts on Just In Time (JIT) and the software process.

In manufacturing, JIT exposes problems. Early discovery means action can be taken to prevent costly systemic failures when conditions change, or are no longer favorable. Thus any part of the process which helps in getting the bad news early is a JIT process.

I am currently reading Test Driven Development for Embedded C.

Test Driven Development (TDD) require tests to be written first. They do not have to be complete. Nor are they written on tablets of stone. But they do have to be written before writing code. And code does not have to wait till all the tests are written. Write one small test. Code a dummy implementation that should fail. Watch the test fail. Then write just enough code for the test to pass. If a "What-if" (or, as some developers in the Tools BU of acmet called them - "Please Consider") strikes you - as inevitably it will - first encapsulate it in a test. Then - and only then - write the code. Keep a note. But no coding.

Coding without the tests is building inventory.

And it is not just that one test that has just been coded that is tested for. All tests must pass every time a test is done. That necessitates automated builds and test harnesses. So if anything breaks the bad news is known straight away.

TDD is JIT.

After Action Reports

Most armed forces worth the name have "After Action Reports" (AAR).

All learning organizations have to have a similar practice, done at regular intervals, as part of their process. A Causal Analysis Meeting, done after every defect fix, was once such practice that we had at acmet.

Recently I came across a misapplication of the term.

A pilot run had some problems. These were identified. Corrections are to be be made for the next lot to be produced.

This is defect correction. An AAR is about defect prevention. For that to happen root causes need to be identified. Taichi Ohno's 5-Whys need to be asked. It needs deliberation

Is Science Just About Prediction?

In a not so recent post Seth Godin asks "are you a scientist?" Scientists, according to him make predictions. And get it right.

That is SO wrong.

Science is about observing phenomena, making hypotheses, testing hypotheses through experiments, and then making a theory that one can use to make predictions. And then not being surprised if the predictions are off, but go back to making hypotheses and experimenting

30,000 ft View

Ever heard the phrase, "the view from 30,000 ft"?

I have learned to be wary of people who use the term. These are people pretending to be leaders. At 30,000 ft you lose touch with reality. Reality is at ground level. God, and the Devil, are in the details.

Yes, the big picture, the vision, is very important. But a vision is of no use unless it is communicated to others. Communication happens where - to use another Americanism - " the rubber meets the road". Unless every day nitty-gritty is linked to the vision, on each small step forward, as well each step back, the vision is useless.

Leadership is exercised from the front. Not from hovering above.

Again on Just In Time

Just in time does not mean waiting till the last moment. Just In Time is to prevent waste. The proverb - "Haste makes waste" - is equally true. Unhurried delivery of worthwhile work is what is required to deliver quality.  

"If I Only Changed The Software ...."

Recently I finished reading the book, "If I Only Changed The Software, Why Is The Phone On Fire?", by Lisa Simone. The book narrates the story of a team developing embedded software.

What Resonated (a very small selection)

1.  Li Mei’s systematic recording of lessons learned and Josie’s insistence on dissemination (page 262-263). That is what creates a learning organization. While an oral tradition is important, it is only documents that transcend space and time.

2.  Pg 261. “ … as long as you put a descriptive comment block above it…”

3.  Pg 261. “... not well architected … you have to wonder what other time bombs …” In other words a Bhoot Bangla

4.  Pg2. “… customer, who pulled one out of the box, turned it on and found the failure.” This is what I call RM’s extension to Murphy’s Law: If anything can fail, it will. And it will happen when the customer is watching.

5.  Pg 240. “… with out realizing there was another one in a different function?” Our Japanese customer taught us this was SUHEI TENKAI.

6.  Pg 141. “The sense of hearing …” Many years ago, when I was young engineering officer in the Indian Air Force, I remember a wizened Warrant Officer telling me, “Sir, these test equipment will tell you a lot, but your five senses will give you your first indication that something is wrong. And in most cases they also tell you what is wrong.” Of course nothing known as embedded those days no digital too (in India).

A must read for embedded software developers. I hope the book comes out in an inexpensive Indian edition.

Just In Time vs Well In Time

This a scene common enough in most examination halls in India.

There are some who keep writing till the invigilator comes and yanks the answer book from them.

There are others who pace themselves and spend the last 30 mins of the 3 hour examination (16% of the "development" time), revising (reviewing) their work.

What about all-night cramming before the exam vs. study spread through the semester?

Which one does your process look like?

Which one would you like it to look like?

Just In Time is easy to misapply.

What Keeps Defects Hidden?

My top five:
1. No daily build and smoke - failure to get the bad news early
2. No unit tests
3. No reviews
4. Code that is hard to understand (follow Linus Thorvald's guidelines)
5. Aggressive scheduling leading to Muri

So when code is not subjected to these it is like work-in-progress widgets inventory piling up at a machine. It is inventory piling up. 

Okay the code works fine, passes all the tests, but there is no user manual. Or it is hard to modify because it is a Bhoot Bangla (going slightly off topic see an oil rig that was one).

When we say we have shipped, did we ship a finished product or was it work-in-progress?

Just In Time for Software

As a readers of this blog would know, I am a great admirer of the Toyota's quality process. I believe that the processes are applicable to software development and renovation.

What puzzled me for a long time was this: How can Just In Time (JIT) apply to software? Software production does not depend upon inventory. To make the second copy of a software product does not require another set of parts to be procured.

Then one day I was talking to my son Vijay, who is a supply chain guy, about Just In Time. He said, "Daddy, Just In Time is about showing up problems in the process".

That was it. I had been looking at the mechanism, not the purpose it was meant to serve.

A software process that exposes defects early is a JIT process.

Which of course begs the question: What is it that keeps defects hidden?