[tor-bugs] #18918 [Core Tor/Tor]: Clarify directory and ORPort checking functions

[Tor Bug Tracker & Wiki]

#18918: Clarify directory and ORPort checking functions
-------------------------------------------------+-------------------------
 Reporter:  teor                                 |          Owner:  (none)
     Type:  defect                               |         Status:  new
 Priority:  Medium                               |      Milestone:  Tor:
                                                 |  0.3.4.x-final
Component:  Core Tor/Tor                         |        Version:  Tor:
                                                 |  0.2.8.1-alpha
 Severity:  Normal                               |     Resolution:
 Keywords:  easy, doc, code, refactor            |  Actual Points:
  technical-debt tor-relay                       |
Parent ID:                                       |         Points:  1
 Reviewer:                                       |        Sponsor:
-------------------------------------------------+-------------------------
Changes (by teor):

 * points:   => 1
 * milestone:  Tor: unspecified => Tor: 0.3.4.x-final


Comment:

 Replying to [comment:9 ffmancera]:
 > I have been reviewing the code these days. I don't think we should
 rename any function but I want to propose some changes in the code
 structure. I will list all the reviewed functions with my notes about
 them.
 >
 >  * `check_whether_orport_reachable()` and
 `check_whether_dirport_reachable()`: I think they are fine, nice
 documentation and names.
 >
 >  * `router_has_bandwidth_to_dirserver()`: Poor documentation, I already
 improved it a bit. Also I think we don't need to check
 `options->BandwidthRate < MIN_BW_TO_ADVERTISE_DIRSERVER` because we are
 checking the same on RelayBandwidthRate.

 Let's rename this to router_has_bandwidth_to_be_dirserver(). "to
 dirserver" is confusing, it could refer to another dirserver.

 See my note below about removing conditions that depend on external code.

 >  * `router_should_be_directory()`: I don't think we need to check
 `advertising != new_choice` and then `new_choice == 1` because we
 initialize both to `1` and within the function only `new_choice` could
 turn into `0`. I already removed this if statement and it works correctly.

 When we remove statements because they are obviously correct, we usually
 insert a tor_assert_nonfatal_once() or if(BUG()) to make sure the
 condition holds. If the condition depends on code outside the function,
 please check it inside the function.

 For consistency, let's rename this to router_should_be_dirserver().

 > * `dir_server_mode()` and `decide_to_advertise_dirport()`: I think they
 are fine, nice documentation and names.

 Let's rename decide_to_advertise_dirport() to
 router_should_advertise_dirport() for consistency.

 > About combine functions, I think we could get
 `router_has_bandwidth_to_be_dirserv` into `router_should_be_directory`.

 If both functions are short, this is ok.
 But if the combined function is longer than a standard terminal window (24
 lines), let's not combine them.

 > Let's decide about do or not these changes and I will work on them :-)

 They sound fine to me. Thanks for working on this ticket!

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