Request: Human-readable alternatives to '@=&' in custom directive scope:{} definitions

[colllin]

I've been using Angular part-time for over a year, and I still have to look up the meaning of @, =, and & in the scope: {} definitions every time I read or write it.

How about:

scope: {
    // These four are equivalent
    title: '@',
    title: '@title',
    title: 'text',
    title: 'text title',

    // These four are equivalent
    model: '=',
    model: '=model',
    model: 'property',
    model: 'property model',

    // These four are equivalent
    onMessage: '&',
    onMessage: '&onMessage',
    onMessage: 'expression',
    onMessage: 'expression onMessage'

}

Obviously, the syntax and naming is up for debate. You guys will have a much better understanding of the bigger picture.

[nfroidure]

👍 would help to start reading angular code easyer

[Narretz]

The problem I see is that "text" doesn't tell you that the binding is only one way, and "property" doesn't tell you that it is two-way. I think you are better off learning the bindings and their implications, rather than having a wrong understanding from the wordings.

[rcollette]

I agree. The binding symbols seem completely arbitrary (though I do understand their implications). Appropriate words should covey the binding behavior.

[caitp]

I think it would be more like interpolate:<name>, bind:<name>, and eval:<name> or something

[pkozlowski-opensource]

The question here is this: do we want to optimise for the learning part or the using part. I totally agree that those symbols are very magical at first but as soon as you understand what is behind those are very concise and convienient to use.

So I guess we could introduce names in addition to symbols but I wouldn't like to see symbols disapear.

[lgalfaso]

agree with @pkozlowski-opensource I would not like the current symbols to disappear

[colllin]

@shahata nice!!

@pkozlowski-opensource
I struggled with these cryptographic symbols from the first moment I saw them. A year later, I still struggle to remember what they represent. That's the whole point -- they're unnatural, even to someone who is relatively experienced with angular. It's extremely disproportionate how often I need to look up these symbols compared to any of the other directive definition properties.

@lgalfaso
I'm not suggesting to remove the current symbols, and that would probably be impossible anyway (for backward compatibility reasons). But ideally the docs would mark them as deprecated in favor of the human-readable versions.

[gkalpak]

To be honest, I don't really think the verbose names will make it any easier on the new-comers. Now instead of having to remember =, @, &, they will have to remember bind, interpolate, eval.

I think most people are comparing their today-self with their one-year-ago self.
Today they probably have a good understanding of what bind, interpolate and eval mean in the context of Angular. They just focus on how hard it was back then to understand and differenciate them and additionally match those 3 mysterious symbols against each concept.
I believe people miss the fact that the most difficult part was understanding how each of the three concepts works, not which symbol refers to which.

I can only imagine new-comers stuggling to understand which concept they need ("Do I need to only read the value or do I need to write it back also ?") and once they decide upon that they will struggle to remember which term describes what they want ("OK, so I just need to read the value, but how's that called ? 'Eval' sounds reasonable, right ? It will evaluate something for me so I get the value. 'Bind' must be that other read-write thing. But wait, what does 'interpolate' do again ? And is it 'eval' or 'evaluate' ? !@#$%^& Angular ... Let me stick with jQuery" :P).

I think the symbols are fine. It's the concepts that have caused us trouble. The symbols are just little tags we put on them so we don't have to remember complex, unintuitive names (like the ones you want to introduce :)). If all these people whimpering about the "weird symbols that make it all so difficult" put their effort into better documenting the concepts themselves, our Angular world would be better.

---

Sorry, for my grumpy tone. I like the symbols. Leave them alone, please :)

[caitp]

Your input is welcome, you should link to this comment on shahata's PR

However, I do think giving the option of using words makes it easier for people to find out about the concepts they're using, because words are actually searchable. You have trouble searching for = and finding anything meaningful

[rcollette]

I totally agree with @caitp regarding searching on the concept itself using symbols. Sure words like eval, bind and text may not convey the behavior clearly but does that mean that there isn't a better set of words, that do convey the behavior. I think it just takes a little more thought about it before shooting it down. What specifically motivates the use of symbols here, above all other places in Angular? If it's ease of use, or typing convenience, why not make $inject=$i, $scope = $s, $eval=$e? There are certain operators represented by symbols that are so common that they are well understood (+, -) etc but that is not the case here. Understanding the concept of what they do is the role of documentation. Identifying a concept is a different matter. The evolution of language has been away from symbols.

It's far too late to take the symbols away. I don't think anyone should worry about that. But I don't think it should preclude the ability to offer a more identifiable alternative going forward.

[gkalpak]

@caitp: As long as the symbols are not deprecated, it's OK by me if new-comers have 3 more keywords to get confused by and search for :)

Since you mentioned searching though, imo, the most difficult thing about directives is that you have to search for $compile in order to find the (quite detailed) docs about directives. Once you make that connection, directives become a whole lot easier :)

[caitp]

I don't think we're going to get rid of the symbols, don't worry about that. The PR doesn't get rid of them, and it's fairly straight forward in how it works, so I think there's pretty minimal harm in merging it. But since it's an exposed API, it needs some discussion

[lgalfaso]

based on #9137 (comment), this is not moving forward

[colllin]

Bummer. Thanks @shahata (#9137 (comment)) for your clear-headed support.