Function prefix comments in C files - Page 3

Do you have a question? Post it now! No Registration Necessary

Translate This Thread From English to

Threaded View
Re: Function prefix comments in C files
NOpeter.bushell@SPAMsoftware-integrity.com says...
Quoted text here. Click to load it

Ahh, now that reminds me of a bug I spent an unreasonable time searching
for (in a commercial RTOS).  They were saving/restoring a pointer that
was used to access some critical internal structure and the access was
left unprotected.  The chip I was using had, unfortuately, a veritable
legion of bugs or so it seemed and so to keep matters simple I had turned
off all the optimizations.  It turned out that when the compiler had its
default (or higher) optimization level on the access to the pointer was
atomic.  With optimization turned off access was no longer atomic and it
turned into a Heisenbug showing up intermittantly and dissappearing as
soon as any attempt was made to find it.  It didn't help that the ICE had
a different set of bugs than the production micro and required a
different set of compiler switches.

When I finally found the bug and reported it to the developers they
claimed that it wasn't a bug since it dissappeared when the optimization
level was increased.  

Annoyingly they had a #define in the code to turn on access protection
around the access to this pointer but had left it undeffed (sp?) since
they 'knew' the compiler would always produce atomic access to the
pointer.


Robert

Re: Function prefix comments in C files
Quoted text here. Click to load it

This will be dependant on your compiler-target combination.  For
example, on an 8-bit micro you can be sure that access to an int will
*not* be atomic (since an int is at least 16 bit).  Thus you need to do
something like disabling interrupts, or doing multiple reads, if reading
the volatile data - if the read is not atomic.  So for accessing
multi-byte volatile data in a safe way, access functions can sometimes
be a good solution (though not necessarily the best or most appropriate
solution).

Quoted text here. Click to load it

Of course you should use functions to ensure safe access to structures
like buffers shared between ISRs and other parts of the program.  I
would not think of such data as "global" in the first place - it is
private to the ISR's module.  But supposing this module (say, a UART
handler) also has a flag variable called "transmitting" that is declared
as a volatile global variable.  Only the UART module will ever change
this flag, but other modules may want to read it.  Where is the harm in
exporting this as a global variable for all to read?

Re: Function prefix comments in C files
On 8 Oct 2005 15:25:50 +0200, David Brown

Quoted text here. Click to load it

You may someday need to use two or three bits for that purpose or
include some other logic, as well.  For example, expanding the
features and functions of your UART handler and doing so without
materially impacting the existing code that already does a good job.
Let's say that in the process of doing so, another bit should be
included in the meaning of 'transmitting'.  You could, of course,
redefine that original bit to include this new meaning, but that might
get into some difficult ISR versus function call from a process timing
problems that were already well worked out before but now become a new
problem, if attempted.  Or it might simply mean modifying code that
has been well tested and works fine and thus risking what's already
been well tested.  So an additional bit might be the lower-risk/better
way to go, but now because you've exported the bit for other code that
option is closed to you.  Having preferred a function to access the
bit means that changes to your design can be a little more readily
contained.

Anyway, there's a potential for 'harm.'  Not that it's necessarily
going to be a real one for any particular application.

Jon

Re: Function prefix comments in C files
On 16 Oct 2005 21:59:16 +0200, David Brown

Quoted text here. Click to load it

Hi, David.  I can't speak to specific situations, of course, as I can
only speak to those I've enough knowledge about.

A designer must weigh various issues and none of what I said should
change any of that.  But I did point out a possible avenue for harm in
exposing a bit to external use.  This doesn't mean that I don't do
that, myself, in some embedded apps.  I was just calling one potential
out onto the table for view _only_ and _because_ you specifically
asked the question and invited a response.

Jon

Re: Function prefix comments in C files
Quoted text here. Click to load it

I agree absolutely, and you are right - there are times when exposing a
variable to external modules can be a problem.  As we both know, the
answer is always "it depends".  My post was more an argument against the
"never use globals, always use functions" crowd rather than the
compromise of "use what is appropriate at the time, but consider future
changes too".

mvh.,

David

Re: Function prefix comments in C files
Quoted text here. Click to load it

Good. What you described, however, are execeptions to the rule ...
and there are *always* exceptions. However, the *rule* from
a portability and maintainability point-of-view is best served
as Peter suggests.

Agreed, however, that in a resource constrained environment,
execeptions are frequently legion.

--
Michael N. Moran           (h) 770 516 7918
5009 Old Field Ct.         (c) 678 521 5460
We've slightly trimmed the long signature. Click to see the full one.
Re: Function prefix comments in C files
On Fri, 07 Oct 2005 13:57:34 -0400, "Michael N. Moran"

Quoted text here. Click to load it


This is why using the newer generation 8-bits are better than using
the older generation 8051, PICs etc. The performance and size impact
is much smaller on the newer generation 8-bits when doing things
"correctly" than for the older generation small MCUs. This is
something which is often forgotten when the various pros and cons
of using one or the other MCU are discussed in this forum.


Regards
  Anton Erasmus


Re: Function prefix comments in C files
Quoted text here. Click to load it

I agree that global variables should be avoided of preference, but I
would not go to the lengths you suggest.  They often provide the most
convenient interface between parts of the program, and using inline
functions for access is not always a good alternative.  There are a
number of reasons for that.  First off, not all compilers are C99 or
have decent inline functions.  Second, adding "access functions" to your
headers adds unnecessary bulk reducing readability.  Third, access
functions don't actually hide the globals - they still need to be
visible to the access functions.  Fourth, if the data is structured,
access functions get much less efficient, much more verbose, and far
less readable.

It is important to know who (i.e., which module and/or functions) have
rights and responsibilities regarding each global variable.  Is the
variable read-only outside the module?  Is it read/write at any time, or
only at specific times?  Should it be volatile?  When is it initialised?
  These are all important questions, and can only be enforced to a
limited degree by access functions, and it is sometimes at the cost of
efficiency (and often at the cost of readability).  The most important
ways to handle these issues, whether you want direct access to globals
or to use access functions, are modularity, structure, and consistency.
  If a global variable "seconds" is defined in the "timers" module, then
you know exactly how it is initialised - by the timers module.  You know
what module has responsibility - the timers module.  You know where to
look for comments regarding its use - the timers module.  There are
certainly times when an access function is the right way, such as when
there must be some locking or synchronising, but dropping all globals is
overkill.

Re: Function prefix comments in C files

(snip)

Quoted text here. Click to load it

(snip)

I was a bit glib about access functions. They can be used to access static
variables but, of course, the functions cannot then be inline. Inline
functions are useful for accessing structure members, given a pointer to the
structure - do you sense some OO going on here? - but the structure
declaration itself must be visible to the compiler at the time. Pity the C99
people didn't add the class concept of privacy at the same time as they
added "inline"!

--
Peter Bushell
http://www.software-integrity.com /



Re: Function prefix comments in C files
Quoted text here. Click to load it

There's a lot that could be done to C to make it a better language, but
it would probably be easier to start from scratch.  Certainly if there
were some way to give compiler-enforced safe and controlled access to
global data without the overhead of functions, I'd use it - but there
isn't.  To paraphrase Winston Churchill, C is the worst possible
language, but it's the best we've got.

Re: Function prefix comments in C files
Quoted text here. Click to load it

<sweat rolls down face>
Must - not - mention - favorite - alternate - language ;-)

--
Michael N. Moran           (h) 770 516 7918
5009 Old Field Ct.         (c) 678 521 5460
We've slightly trimmed the long signature. Click to see the full one.
Re: Function prefix comments in C files

Quoted text here. Click to load it

I often heavily document the function prototypes in the header file.
The intent is that a user need look only in one place for all the
information needed to use the functions prototyped.

Quoted text here. Click to load it

Most editors I use will find such very quickly without using a scroll
wheel, or even a mouse.
Quoted text here. Click to load it
--
Al Balmer
Balmer Consulting
We've slightly trimmed the long signature. Click to see the full one.
Re: Function prefix comments in C files
Quoted text here. Click to load it

I prefer this style:

/*******************************/
Find the configuration value from the Persistent Storage subsystem
identified by ``token'' and store it at ``dest''. Return OK or
BAD_PARAMETER , whatever applies.
/*******************************/

I think the function prototype can be taken for granted. It cannot
reasonably be duplicated in the description, so I don't try.

What I try to tell is, I hate descriptions where the action is
separated from the objects. It is verbose and if taken litterally,
not really watertight.
For example, you could get away with always returning ``OK'' and claim
that it is within spec.

(OTOH, if there is a general remark about error codes on top of
the c-file, you should leave it out of the function description.
That would be okay. )

Quoted text here. Click to load it

--
--
Albert van der Horst, UTRECHT,THE NETHERLANDS
Economic growth -- like all pyramid schemes -- ultimately falters.
We've slightly trimmed the long signature. Click to see the full one.
Re: Function prefix comments in C files
In comp.arch.embedded,
Quoted text here. Click to load it
I see 2 lines of comment with 3 lines of 'code' inbetween, not 5 lines
of comment as you probably intended.

--
Stef    (remove caps, dashes and .invalid from e-mail address to reply by mail)

It is easier to change the specification to fit the program than vice versa.

Site Timeline