Updated and added pages for private class features #5690

meyerweb · 2021-06-04T19:41:35Z

Private class features needed some better explanation on their reference page, and a short-ish guide to their use added. I developed these changes and additions in consultation with folks at Igalia who did the private class feature implementation in Blink.

github-actions · 2021-06-04T19:43:36Z

Preview URLs

Flaws

Note! 3 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/JavaScript/Guide/Working_With_Private_Class_Features
Title: Working with private class features
on GitHub
Flaw count: 2

bad_bcd_links:
- no explanation!
- no explanation!

External URLs

URL: /en-US/docs/Web/JavaScript/Guide/Working_With_Private_Class_Features
Title: Working with private class features
on GitHub

https://github.com/tc39/proposal-class-fields/blob/master/PRIVATE_SYNTAX_FAQ.md (1 time) (Note! This may be a new URL 👀)
https://rfrn.org/~shu/2018/05/02/the-semantics-of-all-js-class-elements.html (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Classes
Title: Classes
on GitHub

https://bugzilla.mozilla.org/show_bug.cgi?id=1428672 (1 time)
https://github.com/tc39/proposal-class-fields (1 time)
https://hacks.mozilla.org/2015/07/es6-in-depth-classes/ (1 time)

URL: /en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields
Title: Private class features
on GitHub

https://v8.dev/features/class-fields (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields
Title: Public class fields
on GitHub

https://v8.dev/features/class-fields (1 time) (Note! This may be a new URL 👀)

(this comment was updated 2021-06-21 18:42:08.099282)

peterbe · 2021-06-07T16:38:29Z

files/en-us/web/javascript/reference/classes/private_class_fields/index.html

 - JavaScript
 - Language feature
-browser-compat: javascript.classes.private_class_fields


As mentioned in the meeting, this might have been a bug in the yari tooling or a matter of a merge conflict of old files.
We should keep this line and then revert back to <p>{{Compat}}</p> somewhere around line 250.

peterbe · 2021-06-07T16:39:12Z

files/en-us/web/javascript/reference/classes/private_class_fields/index.html

+<table class="standard-table">
+  <thead>
+    <tr>
+      <th scope="col">Specification</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{SpecName('Public and private instance fields', '#prod-FieldDefinition',
+        'FieldDefinition')}}</td>
+    </tr>
+  </tbody>
+</table>


Also, these lines should reverted to just {{Specifications}}.

peterbe · 2021-06-07T16:39:26Z

files/en-us/web/javascript/reference/classes/public_class_fields/index.html


 <h2 id="Browser_compatibility">Browser compatibility</h2>

-<p>{{Compat}}</p>
+<p>{{Compat("javascript.classes.public_class_fields")}}</p>


wbamberg

Thanks Eric, this looks great. I had some comments, mostly copy-editing things.

It would be worth drafting a consistent note describing the fact that this is a proposal and not part of the main standard (as I understand it) and using it across all the pages here.

wbamberg · 2021-06-07T17:33:18Z

files/en-us/web/javascript/guide/working_with_private_class_features/index.html

+<p>Private class features deliver truly private fields and methods, with that privacy enforced by the language instead of convention.  This confers benefits such as avoiding naming collisions between class features and the rest of the code base, and allowing classes to expose a very small interface to the rest of the code.</p>
+
+
+<h2>Private Fields</h2>


We use sentence case, so this should probably be "Private fields".

wbamberg · 2021-06-07T17:34:57Z

files/en-us/web/javascript/guide/working_with_private_class_features/index.html

+
+<p>To understand how private fields work, let’s first consider a class that has only public fields, but uses the constructor to encapsulate data—a somewhat common technique, even if it is a bit of a hack.  The following class creates a basic count that accepts a starting number, allows that number to be increased or decreased, and can be reset to the original starting value or any other value.</p>
+
+<pre class="brush: js example-bad">


I'm very much on the fence about this, but giving this example "bad-example" styling feels a little harsh. It's not actually broken after all, it's just not as good as the new thing.

wbamberg · 2021-06-07T17:40:29Z

files/en-us/web/javascript/guide/working_with_private_class_features/index.html

+}
+</pre>
+
+<p>And you can have static private fields, for things you want to be both private and set in stone at construction.</p>


It's weird to have this bit about a thing you can do in the middle of a bit about things you can't do.
Why not an H3 "Static private fields" with this bit, followed by an H3 of "Limitations of private fields" with the rest?

I tried addressing this without adding subheadings in the latest push; let me know if it feels like it works. If not, I’ll see about using headings.

Yes, I like this approach :).

files/en-us/web/javascript/guide/working_with_private_class_features/index.html

wbamberg · 2021-06-07T18:13:58Z

files/en-us/web/javascript/reference/classes/private_class_fields/index.html


 <h2 id="See_also">See also</h2>

 <ul>
  <li><a href="/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields">Public
      class fields</a></li>
-  <li><a href="https://v8.dev/features/class-fields">Public and private class fields</a> article at the v8.dev site.</li>
-  <li><a href="https://github.com/tc39/proposal-class-fields#class-field-declarations-for-javascript">Class field declarations for JavaScript</a> explainer, by the <a href="https://github.com/tc39/proposal-class-fields">Public and private instance fields</a> authors</li>


Link to the new guide page?

wbamberg · 2021-06-07T18:14:29Z

files/en-us/web/javascript/reference/classes/public_class_fields/index.html

@@ -5,14 +5,13 @@
  - Classes
  - JavaScript
  - Language feature
-browser-compat: javascript.classes.public_class_fields


As Peter said above, we should have this in front matter and remove it from the {{Compat}} call.

wbamberg · 2021-06-07T18:16:43Z

files/en-us/web/javascript/reference/classes/public_class_fields/index.html

 ---
 <div>{{JsSidebar("Classes")}}</div>

 <div class="note">
-  <p><strong>Note:</strong> This page describes experimental features.</p>
+  <p><strong>This page describes experimental features.</strong></p>


As noted before we might want to consider using a common form of wording across all three pages for this issue. Perhaps rather than loaded words like "experimental" we could say that it is a proposal and not yet part of the ES spec? Also the formatting of the note has be be pedantically exact for the Markdown conversion to work properly. It has to be <strong>Note:</strong>.

wbamberg · 2021-06-07T18:16:56Z

files/en-us/web/javascript/reference/classes/public_class_fields/index.html


-  <p>Both public and private field declarations are an <a
+  <p>Both Public and private field declarations are an <a


I'm not sure why this change was made.

wbamberg · 2021-06-07T18:17:32Z

files/en-us/web/javascript/reference/classes/public_class_fields/index.html

@@ -275,17 +274,27 @@ <h4 id="Public_instance_methods">Public instance methods</h4>

 <h2 id="Specifications">Specifications</h2>

-{{Specifications}}
+<table class="standard-table">


As before, we should revert this change and just have {{Specifications}} here, then it will pick up the spec link from the BCD front matter item.

meyerweb · 2021-06-08T19:30:00Z

Based on the above conversation(s), I’m going to choose to keep to a single page rather splitting into two pages. Given that, I’ll address the requests and update. Thanks, all!

meyerweb · 2021-06-08T20:15:12Z

I made edits and have pushed changes. I think I addressed all the requested changes, but the way GitHub mixes requests up so that files aren’t grouped together made it hard to be sure. Let me know if anything else is needed.

wbamberg

Thanks for the updates! It looks like the reinstated browser-compat front matter item for public fields needs to be javascript.classes.public_class_fields, not javascript.classes.private_class_fields?

There were a couple of other comments that still might need attention (but please do let me know if you don't think they are applicable):

Updated and added pages for private class features #5690 (comment)
Updated and added pages for private class features #5690 (comment) - it's worth having a link to the reference page from this guide page.
Updated and added pages for private class features #5690 (comment) ... and a link going back the other way...

Finally I wonder if it's worth having some common way to describe the status of these features.

https://pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields has a note saying that public class fields are an experimental stage 3 TC39 proposal.
https://pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields says private fields are stage 3 but not as a note and not mentioning experimental.
https://pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Guide/Working_With_Private_Class_Features doesn't say anything about the status of private fields.

It might be good to use a common message across all three pages - perhaps a modified version of the note in https://pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields ?

wbamberg · 2021-06-09T21:11:17Z

files/en-us/web/javascript/reference/classes/public_class_fields/index.html

@@ -5,7 +5,7 @@
  - Classes
  - JavaScript
  - Language feature
-browser-compat: javascript.classes.public_class_fields
+browser-compat: javascript.classes.private_class_fields


Should this be browser-compat: javascript.classes.public_class_fields ?

~~No, it should be javascript.classes.private_class_fields. They’re different things.~~ I beg your pardon, I misspoke. That was misread and an error on my part, and I’ll fix it. Sorry about that!

(Hit return too soon) As for the two-way links, agreed, and I missed those. I’ll harmonize the warning notes as well. Stand by!

@sideshowbarker makes a good point: the warnings are about to become moot, and should be removed. So I’ll harmonize by removing the warnings and patching the holes. Once more, stand by!

sideshowbarker · 2021-06-10T19:47:55Z

Finally I wonder if it's worth having some common way to describe the status of these features.

* [pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields](https://pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields) has a note saying that public class fields are an experimental stage 3 TC39 proposal.

* [pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields](https://pr5690.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields) says private fields are stage 3 but not as a note and not mentioning experimental.

It seems both of those have outdated status info at this point, and should be removed. See c59c122 and #5850 — the Class Fields proposal was merged into the ES spec in April. And because also in April, Safari 14.1 shipped with full support for class fields, that means all browser engines now have full support.

files/en-us/web/javascript/reference/classes/public_class_fields/index.html

sideshowbarker · 2021-06-10T19:58:53Z

files/en-us/web/javascript/reference/classes/private_class_fields/index.html

  class. There is however <a href="https://github.com/tc39/proposal-private-methods">a
-    stage 3 proposal</a> to allow defining private class fields using a hash
-  <code>#</code> prefix.</p>
+  stage 3 proposal</a> to allow private class features by using a hash


Given that the proposal was merged into the ES spec April, the part part about There is however a stage 3 proposal to allow private class features by using a hash # prefix should be changed to just, However, private class fields can be created using a hash # prefix, or some such.

And also, I think everywhere the content says class properties, it should instead say class fields.

hamishwillee · 2021-06-18T02:51:05Z

What's blocking this? Anything I can do to help?

meyerweb · 2021-06-18T18:13:50Z

What's blocking this? Anything I can do to help?

Actually, I’m not sure if this just needs review, or if it needs more updates. @wbamberg, I think you’re the arbiter of that, yes?

wbamberg · 2021-06-18T18:33:13Z

Most of the comments in #5690 (review) are addressed (thanks!). The only remaining thing in there is to update the various notes and things about it being experimental, not in the ES spec and so on.

@sideshowbarker already removed the note about this from "public class fields" (c59c122), so the only remaining part is the suggestion in #5690 (comment) to drop the reference to stage 3 in "private class fields". With that change I'm 👍 on this PR.

@sideshowbarker also had this comment in #5690 (comment) :

I think everywhere the content says class properties, it should instead say class fields.

meyerweb · 2021-06-21T18:44:00Z

I think I’ve resolved the lingering issues, but let me know if I missed any.

hamishwillee · 2021-06-22T23:07:10Z

@wbamberg Anything else you need from this?

wbamberg

Thanks for all your work on this, Eric!

meyerweb added 3 commits June 3, 2021 14:47

Recovered previous state of private class features page

58ba52e

Restored 'working with...' guide page

3b80848

Edits to privte features guide

8f6fce4

meyerweb requested a review from a team as a code owner June 4, 2021 19:41

meyerweb requested review from sideshowbarker and removed request for a team June 4, 2021 19:41

peterbe reviewed Jun 7, 2021

View reviewed changes

Rumyra mentioned this pull request Jun 7, 2021

[JavaScript] Private fields and private methods are now enabled #5386

Closed

wbamberg requested changes Jun 7, 2021

View reviewed changes

Edits based on requests in mdn#5690

9b6813c

wbamberg requested changes Jun 9, 2021

View reviewed changes

Edits from wbamberg

75cba58

sideshowbarker reviewed Jun 10, 2021

View reviewed changes

Removed warning notes since all browsers will be supporting this stuff

ce83125

hamishwillee mentioned this pull request Jun 14, 2021

FF90 JavaScript Class private features release note/exp features #5970

Merged

meyerweb added 5 commits June 21, 2021 14:34

Updated BCD front matter for public and private class fields

a93f017

Updated BCD front matter for private class fields guide

c175416

Fixed 'properties' usage where needed

920b5bd

Removed Stage 3 warning from javascript/reference/classes/

937f6d8

Merge branch 'main' into private

b697ec8

sideshowbarker approved these changes Jun 22, 2021

View reviewed changes

wbamberg approved these changes Jun 22, 2021

View reviewed changes

wbamberg merged commit 8251599 into mdn:main Jun 22, 2021

github-actions bot locked as resolved and limited conversation to collaborators Aug 3, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated and added pages for private class features #5690

Updated and added pages for private class features #5690

meyerweb commented Jun 4, 2021

github-actions bot commented Jun 4, 2021 •

edited

peterbe Jun 7, 2021

peterbe Jun 7, 2021

peterbe Jun 7, 2021

wbamberg left a comment

wbamberg Jun 7, 2021

wbamberg Jun 7, 2021

wbamberg Jun 7, 2021

meyerweb Jun 9, 2021

wbamberg Jun 10, 2021

wbamberg Jun 7, 2021

wbamberg Jun 7, 2021

wbamberg Jun 7, 2021 •

edited

wbamberg Jun 7, 2021

wbamberg Jun 7, 2021

meyerweb commented Jun 8, 2021

meyerweb commented Jun 8, 2021

wbamberg left a comment

wbamberg Jun 9, 2021

meyerweb Jun 9, 2021 •

edited

meyerweb Jun 9, 2021

meyerweb Jun 10, 2021

sideshowbarker commented Jun 10, 2021

sideshowbarker Jun 10, 2021 •

edited

hamishwillee commented Jun 18, 2021

meyerweb commented Jun 18, 2021

wbamberg commented Jun 18, 2021

meyerweb commented Jun 21, 2021

hamishwillee commented Jun 22, 2021

wbamberg left a comment

		<p>Private class features deliver truly private fields and methods, with that privacy enforced by the language instead of convention. This confers benefits such as avoiding naming collisions between class features and the rest of the code base, and allowing classes to expose a very small interface to the rest of the code.</p>


		<h2>Private Fields</h2>


		<p>To understand how private fields work, let’s first consider a class that has only public fields, but uses the constructor to encapsulate data—a somewhat common technique, even if it is a bit of a hack. The following class creates a basic count that accepts a starting number, allows that number to be increased or decreased, and can be reset to the original starting value or any other value.</p>

		<pre class="brush: js example-bad">


		<p>Both public and private field declarations are an <a
		<p>Both Public and private field declarations are an <a

Updated and added pages for private class features #5690

Updated and added pages for private class features #5690

Conversation

meyerweb commented Jun 4, 2021

github-actions bot commented Jun 4, 2021 • edited

Preview URLs

Flaws

External URLs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg Jun 7, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

meyerweb commented Jun 8, 2021

meyerweb commented Jun 8, 2021

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

meyerweb Jun 9, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sideshowbarker commented Jun 10, 2021

sideshowbarker Jun 10, 2021 • edited

Choose a reason for hiding this comment

hamishwillee commented Jun 18, 2021

meyerweb commented Jun 18, 2021

wbamberg commented Jun 18, 2021

meyerweb commented Jun 21, 2021

hamishwillee commented Jun 22, 2021

wbamberg left a comment

Choose a reason for hiding this comment

github-actions bot commented Jun 4, 2021 •

edited

wbamberg Jun 7, 2021 •

edited

meyerweb Jun 9, 2021 •

edited

sideshowbarker Jun 10, 2021 •

edited