[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
Re: [tor-bugs] #18733 [CollecTor]: contributor's guide incl. coding guidelines for java projects
#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
_______________________________________________
tor-bugs mailing list
tor-bugs@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-bugs