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