hadoop-common-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jakob Homan (JIRA)" <j...@apache.org>
Subject [jira] Commented: (HADOOP-5073) Hadoop 1.0 Interface Classification - scope (visibility - public/private) and stability
Date Wed, 02 Sep 2009 19:22:33 GMT

    [ https://issues.apache.org/jira/browse/HADOOP-5073?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12750625#action_12750625
] 

Jakob Homan commented on HADOOP-5073:
-------------------------------------

bq. Hi Jakob, how are the separated annotations better than a single annotation with a parameter?

With a single annotation and enums, the text added to an element looks like this:
{code}
@Audience(Audience.Type.PUBLIC)
public class HelloWorld {
{code}
compared to separate annotations, which end up looking like:
{code}
@Audience_Public
public class HelloWorld {
{code}
I consider the latter code easier to grok and visually cleaner than the former.  The word
Audience is not repeated, the unnecessary word Type is not included, the odd capitalization
of the Public enum is not included.  Overall, the appearance is that of information meant
for humans rather than computers.

It's possible to create a representation similar to the first example with a single annotation,
as with the above TARDIS class example, or continuing with the current example:
{code}
@Audience(PUBLIC)
public class HelloWorld {
{code}
However, this requires static imports of the Type enum, which my Eclipse (Ganymede) had trouble
doing in a friendly manner.  I ended up having to manually insert them into each file and
even then ran into weird auto-complete behavior.  Eclipse seems to not have a good understanding
of how to deal with static imports.  This is what I meant by IDE integration.  Also, it was
faster to type @A <ctrl-space>P<ctrl-space) and be done with it than it was to deal
with separate enums.  Keystrokes add up.

As far as the generated javadoc, I think it's a wash.  Both approaches are equally readable.

All that being said, this is a minor point and I'm not going to spend many of my lobbying
points on it. 

> Hadoop 1.0 Interface Classification - scope (visibility - public/private) and stability
> ---------------------------------------------------------------------------------------
>
>                 Key: HADOOP-5073
>                 URL: https://issues.apache.org/jira/browse/HADOOP-5073
>             Project: Hadoop Common
>          Issue Type: Sub-task
>            Reporter: Sanjay Radia
>            Assignee: Sanjay Radia
>         Attachments: 5073_demo.png, c5073_20090825.patch, c5073_20090825.png, HADOOP-5073.patch
>
>
> This jira proposes an interface classification for hadoop interfaces.
> The discussion was started in email alias core-dev@hadoop.apache.org in Nov 2008.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message