[tor-bugs] #18733 [CollecTor]: contributor's guide incl. coding guidelines for java projects
Tor Bug Tracker & Wiki
blackhole at torproject.org
Mon Apr 11 09:38:15 UTC 2016
#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
More information about the tor-bugs
mailing list