Re: Bit naming convention

[Dirk Herrmann]

On Fri, 20 Apr 2001, Mikael Djurfeldt wrote:

> 1. Names in Guile usually has a logical order of components.  There
>    are a few exceptions to the rule, but usually we have increasing
>    specificity from left to right.  Following this rule makes it
>    easier and faster to read code.
> 
>    In SCM_ARRAY_FLAG_CONTIGUOUS, FLAG is less specific than ARRAY
>    *and* less specific than CONTIGUOUS.  The correct order would be:
> 
>    SCM_FLAG_ARRAY_CONTIGUOUS.

Hmmm.  This only makes sense if you would like to see all FLAGS in guile
as belonging to some common name space.  I think we should rather group
things in a way that could resemble a modular structure.  For the example
above, I think it makes sense to view support for arrays as something that
could as well be loaded as a module, but just happens to be in the core.

It is somehow a matter of taste, but I think it makes more sense to read
the name like:
  1) Ah, it belongs to the array stuff.  (This means, I can quickly
     decide whether it is of current importance for me.)
  2) It is one of the array type flags.  (I am working on arrays, and now 
     I know it is used for the data type's low level representation.)
  3) Finally it is clear, which binary information actually is
     represented.

It may be true that this is actually not an ordering by specificity, but
it is an ordering that groups according to importance during reading of
code.  According to your suggestion, we have a different order of
categorizing the definition:
  1) Ah, it is a flag for some type's low level representation.  (Note
     that this does not actually help me to decide whether it is of
     current interest for me.)
  2) It belongs to the array stuff.  (_Now_ I can see, whether it is
     something of current importance to me.)
  3) ... as above.

> 2. I think it is confusing that the name of the flag is
>    SCM_ARRAY_FLAG_CONTIGUOUS while the operations on it have the
>    suffix _ARRAY_CONTIGUOUS_FLAG.  Why a different order here?

The different ordering is confusing, I admit it.  On the one hand, I
wanted to follow the style that Michael has chosen in his implementation
of the card based garbage collector.  On the other, well, I thought that
SCM_ARRAY_FLAG_CONTIGUOUS is an ordering that is most helpful for reading
the code.  So, I agree that we should decide for some ordering.  But, I
don't think that FLAGS should be first.  I'd prefer (ordering wise) 
SCM_ARRAY_FLAG_CONTIGUOUS.

> 3. I think 29 characters in names is too much.  It makes code look
>    ugly and makes reading of the code slower.  However, we *do* have
>    the conflicting demand of consistency to pay attention to.

The names are quite long, yes.  And, it can make code look ugly (well -
difficult to say what makes code ugly).  But, I disagree that it makes the
reading of the code slower.  What makes reading of code slower is
unclarity.  Like, before the name of the flag was SCM_ARRAY_CONTIGUOUS.  
This makes reading of code slower, because you have to look it up if only
once in a while you happen to work on the array code, only because it is
unclear that this is actually just a flag.  I have never measured it :-),
but I guess that all the milliseconds that you gain by having to read a
shorter name are lost if you only once need to look up the definition in
some different file because the name is unclear.

[in a later mail you write:]
> BTW, note that flag names occur in logical expressions.  They have an
> even greater need of being short than for example names of functions.

IMO, such expressions are rare and very low level.  They are mostly only
used to create other macros that check for certain properties:  Although
the FLAG name is SCM_ARRAY_FLAG_CONTIGUOUS, the macro that will be used
frequently is actually SCM_ARRAY_CONTINGUOUS_P, and the FLAG is only used
to implement this.  For me, long names for such low level stuff, (which is
not likely to be used or to be changed very often) are acceptable.

> Suggestion:
> 
> We use prefixes like
> 
>   scm_c_   to indicate a function in the API to be called from C code
>   scm_sym_ for symbols
>   etc

Well, we had a discussion about it, but we never actually came to a
conclusion.  It has been practice since then to use scm_c_ for functions
to be called from C, agreed.  But, we have not yet started to rename older
stuff.  And, personally I think that we do not yet have found a consistent
solution, it's just that the discussion died out.

One suggestion that I would like to be discussed, if people want to
discuss such things again, is the following:

  * We use scm_p_ to indicate a primitive function. *

Rationale:  Prefixing primitives in a special way actually brings added
information.  It is clear, that the function returns a SCM value and only
takes SCM arguments.  Further, it indicates that the C level name of the
function and the scheme level name can be derived from each other by
following some translation rules.  Finally, since the scm_p_ prefix does
not yet have any special meaning within guile, a transition is easy.  It
can be started by just adding a lot of #define scm_p_foo scm_foo lines.  
There is currently not a single definition in guile that uses scm_p_ as
its prefix.

Comparison:  The solution to use scm_c_ for functions to be called from C
and scm_ for others starts with the problem, how to represent primitives
that have scheme level names starting with "c-".  Moreover, the current
usage of the scm_ prefix is inconsistent:  It is used for primitive
functions as well as for functions that can only be called from C.  That
means, as long as not all of guile is actually converted to the scm_ /
scm_c_ naming pattern, these names do not help a reader of code:  Until
then, a scm_ prefix does not tell, which return type the function has or
of which type the parameters are.

> I suggest that we add:
> 
>   scm_f_ for flags
>   scm_b_ for bit numbers
> 
> #define SCM_F_ARRAY_CONTIGUOUS 16  /* just an example */
> #define SCM_B_ARRAY_CONTIGUOUS (1 << SCM_ARRAY_CONTIGUOUS)
> #define SCM_SET_F_ARRAY_CONTIGUOUS(...) ...
> 
> (SET is a standardized exception to the specificity rule.)

Hmmm...  

[in a later mail you suggest:]
> The corresponding flag would be:
> 
>   SCM_ARRAYF_CONTIGUOUS
> 
> which is short and nice.  It's still along the lines of specifying in
> the second position the type of object which the name refers to
> similarly to scm_c_ & co.

It is exactly 4 characters shorter than SCM_ARRAY_FLAG_CONTIGUOUS (but, at
least the ordering is the same :-).  And it does not work nicely with
names that end with an F (imagine DIFF to be such a name -> DIFFF :-) or
names that are abbreviations themselves.  Is it really such a big gain?  
I don't think that all these abbreviation rules are helping us.  Some are
OK.  But, we should not overdo it.

Best regards,
Dirk Herrmann