Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[styleguide] Naming convention for ng-template #40996

Open
snebjorn opened this issue Feb 25, 2021 · 4 comments
Open

[styleguide] Naming convention for ng-template #40996

snebjorn opened this issue Feb 25, 2021 · 4 comments

Comments

@snebjorn
Copy link

@snebjorn snebjorn commented Feb 25, 2021

📚 Docs or angular.io bug report

Description

<ng-template #templateName> are awesome! However it becomes a bit unclear if a referenced value is coming from the component or inside the template.

Example

<my-nice-component
    [foo]="bar"
>
</my-nice-component>

In the above example what is bar? Is it a field in the component or a template reference?
When you're inside your editor the Angular Language Service makes this trivial to find out. However when reviewing a pull request it's not clear at all.

So I'd like to propose that we come up with a naming convention for <ng-template>.

It can be something as simple as {camelCaseName}Ref inspired by the TemplateRef type

Then our example becomes

<my-nice-component
    [foo]="barRef"
>
</my-nice-component>

What's the affected URL?

https://github.com/angular/angular/blob/master/aio/content/guide/styleguide.md

@zarend zarend added the comp: docs label Feb 25, 2021
@ngbot ngbot bot added this to the needsTriage milestone Feb 25, 2021
@IgorMinar
Copy link
Member

@IgorMinar IgorMinar commented Feb 25, 2021

I like this suggestion. I've found myself occasionally wondering about some of these variables represent.

I however suggest that if we steer away from the "*Ref" suffix because we have many kinds of Refs so the naming could become confusing.

How about we instead use the "Template" suffix? And at that point, if we are making a recommendation for naming of ng-templates, we can as well make a recommendation for suffixes of elements, components, and directives.

Here is a draft proposal:

<!-- template variable reference for ng-template is suffixed with "Template" -->
<ng-template #usefulTemplate>
  I'm super useful!
</ng-template>

<!-- template variable reference for components is suffixed with "Component" -->
<my-hello #helloComponent></my-hello>

<!-- template variable reference for DOM elements is suffixed with "Element" -->
<p #pElement>
  Some interesting paragraph...
</p>

<!-- template variable reference for exported directives is suffixed with "{DirectiveName}Directive" -->
<form #profileNgFormDirective="ngForm">
</form>

What do you think?

Btw, if we go ahead with this change then we should also update the following guide to conform to the new style:
https://angular.io/guide/template-reference-variables

@snebjorn
Copy link
Author

@snebjorn snebjorn commented Feb 25, 2021

I had forgotten about the others :)
Seems reasonable to suffix them with that they are.

Perhaps some elements merit special treatment.

<!-- template variable reference for input elements is suffixed with "Input"  -->
<input #phoneInput placeholder="phone number">

Hmm maybe that's going overboard. The $ suffix from observables comes to mind.

Now this isn't supported, but perhaps a # suffix

<input #phone# placeholder="phone number">

<button (click)="callPhone(phone#.value)">Call</button>
@Airblader
Copy link
Contributor

@Airblader Airblader commented Feb 26, 2021

The suffix seems a bit magical. Why not just phoneInputElement?

Also, for the purpose of distinguishing component properties from template references, what would a component do which takes a template as an input? Naming it itemTemplate seems logical, but template-side nullifies the intention.

@jelbourn jelbourn added the discussion label Mar 5, 2021
@ngbot ngbot bot modified the milestones: needsTriage, Backlog Mar 5, 2021
@jelbourn
Copy link
Member

@jelbourn jelbourn commented Mar 5, 2021

FWIW I'm not a fan of Hungarian notation in variable naming. I don't really know that this is something that belongs in the Angular style guide versus something that individual teams can decide for themselves.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants