accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher <>
Subject Re: Javadoc contributions
Date Mon, 25 Nov 2013 21:12:44 GMT
I'd say... it depends on what you're documenting and how you're
documenting it. Tests for correct behavior, with comments about the
expectations, are often better than javadocs for internal,
implementing, code and a single ticket for a single set of related
tests/documented expectations seems appropriate. For public API, most
things are already documented, so specific tickets could be opened for
anything overlooked in that area, as needed.

Package and class-level javadocs that explain internal details about
how things work may be useful under a single ticket, if they are
explaining the same overall behavior/architecture, and separate
tickets otherwise (eg. explaining garbage collector implementation,
vs. monitor logging implementation). But, these should probably not
going into too much detail about the specific implementation, or they
will lose relevancy as implementation drifts.

In summary:
1) Class, package, and method-level documentation is welcome for all
things in the public API. (tickets as needed to address anything
overlooked... or supplement existing feature ticket with an additional
commit for javadocs, if a new feature is added and forgets
2) Class and package-level documentation is welcome for internal
implementations, if it helps explain the expected behavior without
going into internal details, which drift and change. (separate tickets
for unrelated architectures/overviews)
3) Keep the comments as local as possible, to avoid drift.
4) For implementing code, it's probably better to write explicit unit
tests, with comments, to test the expected behavior, rather than add
comments to the internal methods themselves, which add bloat and could
become misleading and incorrect over time. (separate tickets for
separate sets of related tests)

Christopher L Tubbs II

On Mon, Nov 25, 2013 at 3:45 PM, Bill Havanki <> wrote:
> In an effort to learn the Accumulo code, I've been working through it and
> writing Javadoc along the way. I'd like to start contributing it to the
> project. Is the best way to do that simply to create new JIRA tickets
> covering the contributions? I have a lot so far, but I would only submit
> digestible portions at a time, so as not to overwhelm anyone.
> Thanks for your advice,
> Bill
> --
> | - - -
> | Bill Havanki
> | Solutions Architect, Cloudera Government Solutions
> | - - -

View raw message