[jira] Commented: (HADOOP-5073) Hadoop 1.0 Interface Classification - scope (visibility - public/private) and stability

["Jakob Homan (JIRA)" <ji...@apache.org>]

    [ 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.