[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 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.

 There are also [https://github.com/google/styleguide style guides] for
 other languages which we could adopt.
 I suppose there is a Tor C-guide, where?


 >  - 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 noticed that we're breaking lines differently than the Google
 document suggests.  But those rules make sense to me, so I'm happy to
 adapt.
 Great, b/c I prefer line breaks before the operator symbol. Doing that it
 is immediatly clear that such a line is a continuation (even when the
 white space is missing). (I think it actually comes from math
 typesetting.)

 >  - I'd want to keep avoiding `// ...` style comments, even though the
 Google documents says in Section 4.8.6.1 that they're okay.
 I thinks so, too. The `//  ` should be avoided and should only be used to
 explain some inner workings of the code.

 >  - We're planning to violate a few of the Javadoc conventions in Section
 7.  We'll have to talk about those.  Maybe we can violate fewer
 conventions or come up with a good rationale for what we're doing and add
 that as exception.
 This should be part of our additional style guide. And, I'd like to set
 the rule: //No comment is better than a wrong or redundant comment//. But
 we could aim at adding more of the usually required tags with time.

 >  - The Oracle Javadoc guide is so long that we cannot reasonably expect
 Metrics Team members to read through that document before contributing.
 Yes and pretty old.
 >  - I also briefly looked at Apache Coding Standards and were thrown off
 by the suggestion to add line breaks before opening brackets, as if Java
 was the same as C.
 That was why I didn't add a link ;-)

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