update style-guide regarding @Metadata

[DartBot]

This issue was originally filed by ross.dart...@gmail.com

---

Now that we have some reflective access to metadata (woot!), it might be a good time to update the style guide regarding best practices.

I've written up my thoughts about this here:
http://futureperfect.info/2013/06/20/a-case-for-metadata.html

The point that (I believe) needs to be addressed, is that current annotations such as @override or @observe don't mix well with annotations that use constant constructors, such as a fictional @ExpectError(StateError)

cheers,

[dgrove]

Set owner to @munificent.
Added Area-StyleGuide, Triaged labels.

[sigmundch]

Issue #14149 has been merged into this issue.

[sigmundch]

Marked this as blocking #14860.

[sigmundch]

Marked this as blocking #15159.

[sigmundch]

Thanks Ross for putting together those notes.

I mentioned this in a related bug, but I'll copy it here so we can have style discussions in a single place.

I think annotations are different enough to deserve different style rules.

In my opinion @­ALL_CAPS is not easy read, and I personally find @­foo more readable than @­Foo(). I'm open to have an exclusion in the style-guide saying that classes intended for annotations can be named differently, so you can user them as @­lowerCamelCase or @­lower_case_with_underscores.

I think this is ok because we rarely, if ever, use a class both for code and for annotations.

[peter-ahe-google]

My preference is to define lower case constants when they are intended for use as annotations, and keep the current conventions for class names. So:

const deprecated = const Deprecated();

@deprecated foo() {}

@deprecated() bar() {}

[DartBot]

This comment was originally written by @seaneagan

---

Siggi,

Thanks for starting this discussion!

Regarding readability, if issue #2 were fixed, what would you then find more readable:

@foo
@foo

For me, it's @­Foo because:

* that's what I'm used to with java/C#

• it reads similar to a type annotation (e.g. Comparable)

[DartBot]

This comment was originally written by @seaneagan

---

@6 (Peter): It seems unfortunate that every annotation would need to have a parallel named top-level constant, just so () can be omitted at the use site. That means:

* extra API surface
  - 2 ways to do the same thing (@­deprecated, @­Deprecated())
  - duplicate documentation.

• name shadowing due to an abundance of top-level variables (e.g. imported @target shadowed by local target constant, no error given when using @target)

issue #2 solves all this by allowing @­Deprecated

[peter-ahe-google]

You don't need to duplicate anything, I only used "deprecated" to illustrate my opinion on naming conventions.

If it wasn't too late, I'd argue that we should remove "deprecated".

[DartBot]

This comment was originally written by @seaneagan

---

Here is the style guide rule that I believe we need:

PREFER exposing constructor invocation annotations ( e.g. @­Foo() ) over top-level variable annotations ( e.g. @­foo ).

This provides a more consistent experience for annotation users. It also future proofs the annotation for adding optional parameters in the future ( e.g. @­Foo(bar: baz) ). There is also the possibility that the user will be able to omit the () in the future (see http://dartbug.com/13582), which would make it just as short ( e.g. @­Foo ) anyways.

GOOD:

    class Foo() {
      const Foo();
    }

    // ...

    @­Foo() method();

BAD:

    class _Foo() {
      const _Foo();
    }

    const foo = const _Foo();

    // ...

    @­foo method();

[DartBot]

This comment was originally written by ross.dart....@gmail.com

---

I'm happy to see this conversation happening, and thankful for Sean's persistence :)

This appears to be a fairly subjective topic. For what it is worth, I am in favor of comment #­10. In the 5 months since I wrote this original issue, I have worked quite a bit with annotations in Dart. Probably the only notable thing I could say now is that I have gotten used to the way it is. I'm afraid we may end up with a 50/50 split of lowercase and Uppercase annotations, like we have with /// and /** */ doc comments, unless there is strong pressure to go one way or the other, as there seem to be strong preferences out there for both ways. Maybe that is okay.

[peter-ahe-google]

I strongly agree with the last sentence of comment #­11 :-)

[DartBot]

This comment was originally written by @seaneagan

---

I feel like the main (only ?) reason some folks prefer @­foo is they can't have @­Foo (issue #2), but maybe I'm wrong, and at least I would be much happier to use natural selection to resolve this if one of the selections wasn't artificially hobbled with the () tax :).

[munificent]

TL;DR at the bottom...

OK, so I scraped all of the packages in pub and did some digging to see how people are using annotations right now.

I found 832 usages of capitalized annotations. The most frequent ones were:

• @­Test() (386 usages)
• @­NgDirective() (99 usages)
• @­CustomTag() (85 usages)
• @­NgComponent() (24 usages)

I found 2737 usages of lowercase annotations. The most frequent were:

• @­override (2018 usages)
• @­observable (194 usages)
• @­deprecated (181 usages)
• @­published (154 usages)
• @­protected (51 usages)
• @­specification (40 usages)
• @­reflectable (40 usages)

This seems like lowercase is the clear winner. However, that's dominated by the three annotations in corelib: @­override, @­deprecated, and @­protected. If you omit those, there are 487 remaing usages of lowercase annotations.

If you look at the different kinds of annotations, we have:

• 74 different capitalized annotations
• 23 different lowercase annotations

I found several capitalized annotations without parameters (so presumably references to classes). I also found a few lowercase annotations with parameters, so lowercase class names like @­groupdoc('Multi groupdoc') and @­specification(name: "contains()").

Of the constructor annotations (i.e. ones with parameters), I found all manner of optional, positional, and named parameters. It's clear that people are using the flexibility of parameter lists to constructors. There are a number of cases where an empty parameter list is being used.

I even found a couple of named constructors like @­WithState.visible().

My intuition from this data is that there are a few annotations that feel like they are part of the language itself, almost like pseudo-reserved words. People seem to prefer those to be lowercase, like @­override and @­protected.

Some frameworks like polymer have also chosen lowercase, like @­observable and @­published.

But, outside of those, the wide majority of annotations are actually capitalized class constructor calls. Further, users are taking advantage of parameter lists in many cases there.

Given that, I feel that the style guide should not go out of its way to encourage people to make constants to hide their annotation classes behind. There's no need to do:

class Foo { const Foo(); }
const foo = const Foo();

When people seem perfectly comfortable doing @­Foo or @­Foo() and this gives you more flexibility going forward.

However, I don't think we should prohibit making constants for your annotations. For some cases where the annotation is really frequently used, people seem to like something visually lighter.

The only issue with that is that it conflicts with our ALL_CAPS guideline for constants. My belief is that the style guide should change that rule. We don't currently apply it consistently, and we've frequently found exceptions to it. I've never liked it and don't think it adds value.

Instead, I think the style guide should say that some constants are ALL_CAPS and others are lowerCamelCase and either style is acceptable.

TL;DR: I want feedback, but my current belief is that we should make these changes to the style guide:

1. For classes to be used in annotations say that they are named normally. This isn't strictly necessary, but it clarifies things.
2. Say annotations are normally just class constructors or class literals if you want to leave off the "()".
3. But for annotations that will be heavily used, it's OK to define a constant with a lowercase name and have users use that.
4. Constants can be lowerCamelCase or ALL_CAPS, with a slight preference for the former.

Thoughts?

[peter-ahe-google]

I like Bob's suggestion, but I'll note that the bit about class literals in annotations should be removed for now. Shortly before shipping 1.0, it was made illegal to use class literals in annotations because it was feared that Java programmers would be confused.