[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Pointer and internal/external symbol naming

Quoting from "CodingStandard.pdf":

All internal global symbols have s "_ppx" or "ppx_" prefix
Symbols of global scope that are only used internally have to be prefixed
with either
"pp_"/"ppg_"/... (preferred as it preserves the leading "pp") or

I think that is somewhat counterproductive. The intention, of course, is not
to pollute the public namespace with PPlay internal symbols. A worthy and
nessecary aim. I, however, think there is a better solution. But first,
where this solution shows its weaknesses.

Wheter a symbol is internal or external, is completely and utterly
inconsequential for PPlay code. In the effort to remove dependencies (keep
code on a need-to-know basis), it should be clear that this is a clear
example of a situation in which the principle of data-hiding should be
applied. If X doesn't care if Y has or doens't have a property Z, X will
function regardless of wheter or not Y has property Z. This is obviously
both principally and practically beneficial.

Naming internal symbols different than extrenal symbols introduces an
dependency in PPlay code on wheter or not a symbol has the property of being
external or internal. For the reasons stated above, this dependency is bad
and should, if in any way possible, be removed (that, and we shorten all the
internal symbols by a "_" :).

If it was a question of either having this dependency, or polluting the
global namespace with the possibility of name-clashes as a result, then we
would have to keep the dependency.

However, this is not the situation. The simple solution is to use
namespaces. All internal code go to ::pp::internal and all external code go
to ::pp (something shorter than "internal" probably would be advisable).
That would work.

However, this, atleast at first, doesn't seem to remove the dependency in
code on wheter a symbol is external or not, since external parts of PPlay
would have to prefix "internal::" to references to internal parts. There is,
however, an (IMHO) elegant work-around for this: declare everything in the
namespace ::pp::internal. No, I haven't lost my marbles :)

Now, we have everything in ::pp::internal, and nothing in ::pp. This seems
not to be a big improvement, but it is. The reason is that we can include
all external parts of PPlay from ::pp::internal into ::pp. Not using "using
namespace internal", mind you, but by "using internal::symbol" for each
external symbol (you can use "using" that way, right? If not, use typedef

Since all external parts of PPlay really are ALSO internal parts (ie, used
internally), it only makes perfect sense that they should be found in both
the internal and external collection (read: namespace) of symbols.

What do people think?


This leads me, not very elegantly, on to pointer-variable naming. How about
prefixing pointers with "p" ? So "char* name" becomes "char* pName", "char*
obj" becomes "char* pObj" etc.

This has numerous benefits.

You will always be completely sure wheter or not a variable is a pointer or
not, regardless of wheter or not you are looking at, or ever have looked at,
its declaration.

Pointer is a distinct variable type for which special rules exist. You can
indirect them. You can delete them. They follow special pointer-arithmetic
rules. By working with them, you can alter the value of variables at other
addresses in memory. Incorrect usage can sometimes corrupt memory and bring
the complete process to a halt or make it show completely inappropiate and
random behavior (even, in rare cirsumstances, malicious behavior).

When working with pointers, it is very important to always remember that
what one is working with is pointers. Forgetting can lead to all sorts of
nastiness, like memory leaks, memory curruption and stray pointers. These
are all bugs that can be extremely hard to detect. Making it very clear and
explicit that a variable is a pointer helps prevent this. The by far fastest
way of producing bug-free code, is to not make bugs in the first place.

Also, its possible to forget that a pointer is a pointer and treat it like
an integer or floating-point variable, *without* the compiler thinking
anything of it. Things can get especially hairy if a variable is changed
from a pointer to a non-pointer type. The compiler will very clearly direct
you to the places in which behavior has changed if pointers are prefixed
with "p" and non-pointers aren't.

In documentation, you can also say simply "the variable pStr" or "the
argument pStr" rather than "the pointer variable str" or "the pointer
argument str", which you would have to say to make it clear what you ment.

This is a case of data hiding being non-beneficial since even if X can
function nomatter wheter or not Y has property Z or not, X will only
function correctly if Y has property Z (or hasn't, whatever the case may
be). We want the compiler to tell us things like that. The cheapest bugs are
those picked up at compile-time.

What's the sentiment for this?