[tor-bugs] #29209 [Core Tor/Tor]: Reduce visibility of more data type internals

[Tor Bug Tracker & Wiki]

#29209: Reduce visibility of more data type internals
----------------------------------------+----------------------------------
 Reporter:  nickm                       |          Owner:  (none)
     Type:  task                        |         Status:  needs_review
 Priority:  Medium                      |      Milestone:  Tor:
                                        |  0.4.1.x-final
Component:  Core Tor/Tor                |        Version:
 Severity:  Normal                      |     Resolution:
 Keywords:  technical-debt refactoring  |  Actual Points:  3.5
Parent ID:                              |         Points:  15
 Reviewer:  nickm                       |        Sponsor:  Sponsor31-can
----------------------------------------+----------------------------------

Comment (by catalyst):

 Replying to [comment:10 asn]:
 > So to understand this better. How would that look for the patch in
 #30236? Would we have to turn `crypto` into `my_crypto` when `PRIVATE` is
 set? I think turning it into `pvt_crypto` or `local_crypto` might even be
 ambiguous in terms of cryptography. `my_crypto` can also be a bit
 ambiguous but let's ignore this for now.
 >
 > Also, is it fine to have a macro definition be named in lowercase? Could
 this be confusing?

 I think yes, it's ok to have a lowercase macro as long as its not widely
 exposed and has a reasonable prefix to control the namespace. The purpose
 of such a member-renaming macro is to be mostly invisible to the
 developer.

 > If we are fine with the above, that seems like a plausible way to go
 forward and I can change my patch for #30236.
 >
 > (BTW, I lost your discussion in #tor-dev (i guess) about this because my
 irc host rebooted).
 I think the way this tended to work in historical Unix is that struct
 members all have very short prefixes (1-3 characters and an underscore) to
 their names, which made the namespacing of the macros more manageable.
 (e.g., `sa_` for `struct sockaddr` or `sin_` for `struct sockaddr_in`.)
 The macro expansion and actual member name, of course, could be longer
 because we don't expect developers to manually write it.

 Example, using `f_` as a prefix (let's not actually do that particular
 prefix, because POSIX reserves it for some header)
 {{{
 struct foobar_t {
   int f_count;
   char *_f__private_thing;
   long f_id;
 };
 #ifdef FOOBAR_PRIVATE
 #define f_thing _f__private_thing
 #endif
 }}}

 or maybe with a helper macro like
 {{{
 #define F_PRIV(x) _f__private_ ## x
 }}}

 or

 {{{
 #define F_PRIV(x) x ## _ ## _private
 struct foobar_t {
   int f_count;
   char *F_PRIV(f_thing);
   long f_id;
 };
 #ifdef FOOBAR_PRIVATE
 #define f_thing F_PRIV(f_thing)
 #endif
 }}}

 For more background, there's
 http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_02_02
 and
 http://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xsh_chap02.html#tag_22_02_02_04
 from the POSIX standard.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/29209#comment:11>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online