[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):

 Thanks for posting these links.  I read/skimmed all three documents.  My
 first impression is that the Oracle documents are rather lengthy and a
 little cumbersome to read whereas the Google document seems to be more
 pratcial.  The Google document also matches more closely what we're doing,
 so we'd have to change fewer things to comply with it.  I also realized
 that I really want to avoid writing or maintaining a similar document for
 our guidelines and instead adapt our coding practices towards what other
 people do, maybe with just a few exceptions.

 More detailed feedback:
  - 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.
  - 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.
  - I'd want to keep avoiding `// ...` style comments, even though the
 Google documents says in Section 4.8.6.1 that they're okay.
  - 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.
  - The Oracle style guide has some suggestions for indentation that I find
 quite ugly, including using 4 spaces for indents and aligning subsequent
 lines with an expression in the previous line.
  - The Oracle Javadoc guide is so long that we cannot reasonably expect
 Metrics Team members to read through that document before contributing.
  - 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.

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