My last post, quite a while ago, expressed my preference for putting usage comments (as opposed to implementation comments), as far as possible, in header files on the grounds that the header file is the primary interface which the user has with the code. The code file (.c or .cpp), from a user’s perspective, contains a lot of irrelevant text and may not even be available for inspection in any case.
I did, however, write:
I’ve used several approaches but I’ve yet to settle on a “best” one. Indeed, the concept of “best” hinges to some extent on the approach, if any, taken with regard to external code documentation
Doxygen is perhaps the most popular open source tool for producing extensive, structured, external documentation by extracting comments (which have some special formatting) from the source files. As it can extract from both header and code files, the question is re-opened as to where it is best to put the usage comments. Read more…
An excellent and succinct article by Michael Barr entitled “What Belongs in a C .h Header File?” triggered the thoughts I am about to write down, for he forgot to mention comments as worthy items to be included. When conducting Advanced C courses, as I sometimes do, I have always emphasised the need for usage comments in header files. Header files provide the user’s interface to the implementation in the corresponding .c files, but the latter are often uninteresting to the user and may not even be available. Proprietary libraries, for example, are typically shipped in object form with their header files. It follows, therefore, that any comments which might be valuable to the user should be in the header file. Read more…
Most embedded software practitioners – sadly, not all – know that some form of what is normally called “Mutual Exclusion” is necessary when a read-write resource is shared among two or more concurrent activities, particularly (but not necessarily only) when test-and-set operations are involved. The expression “Mutual Exclusion” is so entrenched as a generic concept that I feel obliged to use it as such, but sometimes it is anything but mutual. Read more…
Since Easter, when I promised a new release of this software, I’ve been exceptionally busy in a money-earning sort of way. I’ve noticed that others are blogging less now that their business has (presumably) picked up, so I’m not alone in disappointing my readers, but that is no excuse and so I have just uploaded the software I promised. Read more…
I like C++, but sometimes it appears to work with the aid of magic which I don’t fully understand. Last time (was it really 3 weeks ago?) I mentioned a problem I had with compiling the software I have been offering to subscribers to this blog with the GNU compiler. Or, to put it more honestly, I created a problem which g++ legitimately complained about, but which the other two compilers I tried (VC++ and IAR) allowed me to get away with. I am simplifying somewhat but basically I coded something like this: Read more…
The free software you may have downloaded from this site embodies an error of principle (details another time). It compiles with VC++ and IAR (ARM), and the code is correct and runs properly. However, I tried g++ today and it was less forgiving. Unfortunately, it’s right and I’m wrong, even though I got away with it up to now. I’m working on a fix and will post again when I have finished it.
The C++ dynamic memory software I published last week has been updated with a small but useful enhancement.
Find out more by downloading it: start by going to the Subscribers’ page.
For the last couple of months, my software efforts have been diluted by the need to attend to other matters no less important but somewhat distracting. Now I have finally released some software. It is not the whole of SKC++, though. I learned so many things, at a detailed level (mainly about C++), in developing SKC++ that I realised that I had built “one to throw away”, as the saying goes. The refactoring is well underway and I have decided initially to release some of the essential elements of SKC++ in stages, as library modules which can be used more generally Read more…
You can now register automatically as a Subscriber to this blog. Just go to the “Subscribers” page and follow the instructions there.
The previous posting tells you why you might want to subscribe.
It is now possible to subscribe to this blog. Subscribers (only) will be able to download various pieces of software which I will begin soon to make available. Subscribers will also be able to see any private blog entries I might make, which will be invisible to casual visitors. Read more…