Opened 3 months ago

Last modified 3 days ago

#29223 needs_review task

List canonical abbreviations to use in Tor functions and identifiers

Reported by: nickm Owned by: nickm
Priority: Medium Milestone: Tor: 0.4.1.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords:
Cc: Actual Points: .7
Parent ID: Points: 1
Reviewer: teor Sponsor: Sponsor31-must

Description

We often don't abbreviate things in our function names and global identifiers. This leads to beautiful things like "router_get_mutable_consensus_status_by_descriptor_digest" and "signed_descs_update_status_from_consensus_networkstatus" and "networkstatus_consensus_can_use_multiple_directories".

What's more, when we do abbreviate, we often do so inconsistently: cfg versus config, con vs conn, orconn vs or_conn, and so on.

We should specify which abbreviations we want to standardize, and converge on those.

It is most important to do this for identifiers that are visible across modules, followed by identifiers that are global within a module. I don't think we need to do this for local variables.

Child Tickets

Attachments (2)

abbrevs-today.txt (8.2 KB) - added by nickm 9 days ago.
abbrevs-proposed.txt (9.4 KB) - added by nickm 8 days ago.

Download all attachments as: .zip

Change History (13)

comment:1 Changed 3 weeks ago by gaba

Points: 0.51

comment:2 Changed 11 days ago by nickm

Milestone: Tor: 0.4.1.x-final

comment:3 Changed 10 days ago by gaba

Sponsor: Sponsor31-must

Changed 9 days ago by nickm

Attachment: abbrevs-today.txt added

comment:4 Changed 9 days ago by nickm

I've attached a file documenting all the abbreviations that are currently in use in function names. Some of them collide; some are ambiguous; some long terms in frequent use are missing abbreviations.

Next steps here are to identify preferred versions (or not) for all ambiguous abbreviations; decide what to rectify and what to grandfather in; and make a (proposed) canonical list.

Changed 8 days ago by nickm

Attachment: abbrevs-proposed.txt added

comment:5 Changed 8 days ago by nickm

Actual Points: .7
Status: newneeds_review

I've attached a second file, proposing to standardize on certain abbreviations, add new ones, and decline to abbreviate other things. I'm hoping that we come up with a good compromise between readability and terseness, though I recognize that no compromise will be optimal for everybody.

comment:6 Changed 5 days ago by nickm

Owner: set to nickm
Status: needs_reviewaccepted

comment:7 Changed 5 days ago by nickm

Status: acceptedneeds_review

comment:8 Changed 5 days ago by asn

Reviewer: teor

comment:9 Changed 5 days ago by teor

I want to make comments on this file, and I'd usually do that through a pull request.
Where is it going to live?
I think I'll start by dumping it in doc/HACKING, and we can move it to its final location later,

I also have a broader question:

Are identifiers in the tor specifications in scope?
Juga and I spent a lot of time trying to name fields for the bandwidth file.
A set of standard abbreviations would have been very useful.

comment:10 in reply to:  9 Changed 4 days ago by nickm

Replying to teor:

I want to make comments on this file, and I'd usually do that through a pull request.
Where is it going to live?

I don't know yet; I was undecided between doc/HACKING, the wiki, or something else.

I think I'll start by dumping it in doc/HACKING, and we can move it to its final location later,

That's fine.

I also have a broader question:

Are identifiers in the tor specifications in scope?
Juga and I spent a lot of time trying to name fields for the bandwidth file.
A set of standard abbreviations would have been very useful.

This list does not try to cover the specification, but having a consistent set of abbreviations and symbols to use there would be good.

comment:11 Changed 3 days ago by teor

I have reviewed about half of this list, I'll submit my review now. I'll finish the rest tomorrow.

Note: See TracTickets for help on using tickets.