[tor-bugs] #27253 [Core Tor/Stem]: Decide: rename Size subclasses to indicate unsigned and bit counts

[Tor Bug Tracker & Wiki]

#27253: Decide: rename Size subclasses to indicate unsigned and bit counts
-----------------------------------------+------------------------------
 Reporter:  dmr                          |          Owner:  atagar
     Type:  enhancement                  |         Status:  needs_review
 Priority:  Medium                       |      Milestone:
Component:  Core Tor/Stem                |        Version:
 Severity:  Normal                       |     Resolution:
 Keywords:  client dev code-improvement  |  Actual Points:
Parent ID:                               |         Points:
 Reviewer:  atagar                       |        Sponsor:
-----------------------------------------+------------------------------

Comment (by teor):

 Replying to [ticket:27253 dmr]:
 > From [[ticket:26227#comment:4]]:
 > > ==== Naming: `stem.client.datatype.Size` subclasses/attributes
 > > **Suggestion**:
 > > It might be good to switch `CHAR`/`SHORT`/etc. to
 `UCHAR`/`USHORT`/etc.
 > > I don't know what the convention is here, but it may help for
 readability.
 > >
 > > I'm personally used to `U<size>` to signify unsigned and `<size>` to
 signify signed. I think switching to `U<size>` would make the code
 //potentially// easier to read for newcomers from various backgrounds.

 C uses unsigned types because certain operations (overflow, bit shifting)
 are defined on unsigned types, but undefined or produce unexpected results
 on signed types.

 > > **Suggestion**:
 > > Similarly, it may help to put the bits length in it, too - for the
 most immediate readability.
 > > So, e.g.:
 > > * `UCHAR8`
 > > * `USHORT16`
 > > * etc.
 > >
 > > For reference, on a quick glance...
 > > * [[https://gitweb.torproject.org/trunnel.git/tree/README|trunnel]]
 [[https://gitweb.torproject.org/trunnel.git/tree/lib/trunnel/Grammar.py?id=c6e8a499f5a5f00113ea268cfcef9e7676c6ed96#n86|appears
 to use]] `u8`, `u16`, etc.

 Trunnel is a custom data declaration language, its conventions are likely
 an abbreviation of the C standard.

 Trunnel integer types also happen to have the same names as Rust integer
 types:
 https://doc.rust-lang.org/book/2018-edition/ch03-02-data-types.html
 #integer-types

 > > * `tor`
 [[https://gitweb.torproject.org/tor.git/tree/src/common/torint.h?id=1b04dab60c549d9f0d621e1a115cab8a49c839f9|appears
 to use]] `uint8_t`, `uint16_t`, etc.

 These types are defined in the C standard:
 http://pubs.opengroup.org/onlinepubs/009695399/basedefs/stdint.h.html

 I encourage you to follow python conventions, whatever they are.

 > atagar: thoughts?

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