[tor-bugs] #18733 [CollecTor]: contributor's guide incl. coding guidelines for java projects

[Tor Bug Tracker & Wiki]

#18733: contributor's guide incl. coding guidelines for java projects
-----------------------+--------------------------
 Reporter:  iwakeh     |          Owner:  iwakeh
     Type:  task       |         Status:  assigned
 Priority:  Medium     |      Milestone:
Component:  CollecTor  |        Version:
 Severity:  Normal     |     Resolution:
 Keywords:  ctip       |  Actual Points:
Parent ID:  #18730     |         Points:
 Reviewer:             |        Sponsor:
-----------------------+--------------------------

Comment (by karsten):

 Replying to [comment:4 iwakeh]:
 > Thanks for your comments!
 >
 > I agree the Google guide is the most pragmatic and concise one.
 > As it is under CC-By 3.0 License we could just have the current version
 with the licensing info as reference document in the `metrics-team` git
 with an additional very short document that states the differences and
 extensions we want.

 Works for me, but let's get team buy-in for this by either discussing it
 at the next team IRC meeting or repeating this suggestion on the metrics-
 team@ mailing list and asking for objections.  Maybe we'll come up with
 more suggestions like that at this Thursday's meeting that we can send to
 the list in a single message.

 > There are also [https://github.com/google/styleguide style guides] for
 other languages which we could adopt.

 Yes, I noticed.  I can't say how practical those are, but I'd say they're
 definitely candidates to consider when picking a guide for other
 languages.

 > I suppose there is a Tor C-guide, where?

 This document looks pretty close to what you're looking for:

 https://gitweb.torproject.org/tor.git/tree/doc/HACKING/CodingStandards.md

 > >  - The Google document says in Section 3.4.2 that "each class [should]
 order its members in some logical order, which its maintainer could
 explain if asked."  A while ago I read parts of Robert C. Martin's book
 Clean Code where he describes the Step-down Rule
 (http://www.itiseezee.com/?p=119).  I would like to suggest we use that in
 Metrics code bases.  That would be one of the exceptions/additions that
 we'd have to make in addition to reference an existing style guide.
 > Well, step-down rule is ok with one minor change: I'd always want the
 lower level function after its first occurrence.

 I think I agree with that ordering, but let me give an example and hear
 from you whether that's what you had in mind:

 {{{
 class A {
   int a;
   int b;
   void m() {
     n();
     p();
   }
   void n() {
     o();
   }
   void o() {}
   void p() {}
 }
 }}}

 Your preference is to put `o()` above of `p()`, because `o()` is the
 lower-level function that gets called in `n()`?  Hmm, or would `p()` go
 first, because it's a lower-level function called in `m()`?

 And also just to be sure, attributes would go above all methods in this
 scheme, not above (or even below) methods where they're first used?

 (I agree with the rest of what you're saying, so I'm not repeating that
 here.)

 Thank you, this is important work, even if it doesn't produce a single
 line of code right now.  But it will produce better code very soon. :)

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