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.
2 comments:
Yes, Change log (Version history) make it easy and fast to adapt the change. Also if versioned properly, the user has a better idea of what version to use.
Yes. Change logs make life easy for the users. It helps in quickly adapting the new version. And if the changes are versioned properly, then the user has more power to decide whether to use the new set of changes or not.
Post a Comment