jQuery Forum

I'd like to respectfully disagree. I find prefixing private methods
with underscores very valuable and keeps methods which should not be
used externally from being used. It also provides a nice measure of
organization which I enjoy. Both of these reasons make the underscore
prefix valuable in my mind and I make frequent use of the feature. I
don't feel Jörn's argument is sufficient for removing this from the
core.
Just my 2 cents.

In addition, there is a large audience of users who prefer to interact directly with the plugin instances, which don't prevent access to "private" methods.

For an example see the contextmenu: <a href="http://jquery-ui.googlecode.com/svn/branches/dev/tests/visual/menu/contextmenu.html">http://jquery-ui.googlecode.com/svn/branches/dev/tests/visual/menu/contextmenu.html</a>
Having all menu methods public by default makes the interaction with the Menu widget very easy to code here.
Andrew, would you mind commenting on the emergent-design aspect? Thats the main reason here, that is, I care much more for API design then for coding style.
Jörn

Sorry that was so long-winded. Just to be clear, and in short, I have absolutely no problem with anyone writing plugins where all methods are public, even if some are undocumented. That said, we shouldn't simply remove all underscores from methods that weren't ever written with that in mind.
- Richard

There is a conflict between "safe" and "open" API exploration. Both have their merits. How about keeping private methods as they are, while experimenting with a more open approach in the new widgets?
Jörn

Sounds like a plan to me.
- Richard

<div class="gmail_quote">On Tue, Dec 15, 2009 at 9:01 PM, Richard D. Worth <span dir="ltr"><<a href="mailto:rdworth@gmail.com">rdworth@gmail.com</a>></span> wrote:
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
* If you remove the underscore, the user has no warning they're using an undocumented, unsupported, and untested method. Except lack of documentation? So they're encouraged to explore the code and use whatever they find, but they're supposed to know well enough to only depend on things that are documented. And that documentation exists elsewhere, and is almost sure to be incomplete and out-of-date, especially if the code is not yet released. This is a case where it helps a great deal for the code to be self-documenting.
</blockquote><div>
agreed
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote"><div>
* What if the documentation for that method is missing, but it's actually public and supported? What would indicate so, and that it should be documented?
</div></div></blockquote><div>
agree this would be a problem
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote"><div>* What if a method is internal, but someone doesn't know that, and seeing the documentation is missing, writes documentation for it? When does the team accept the commitment to support the behavior of that method? When the code is released? When the documentation is written?
</div></div></blockquote><div>
agree that would be a problem
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote">
<div>
* Someone says "hey, do this, it works" and other people try and find out it does, only to see in the next version it breaks without warning and with no mention of it in the release notes because they depended on an undocumented method. Add to this scenario plugin extensions that are written and depend on internal methods that subsequently other people depend on, that then break, not because the user used an undocumented method, but because the user included a plugin extension that made use of an undocumented method. Not having a clean API line will make it extremely difficult, if even possible, to refactor these plugin cores.
</div></div></blockquote><div>
Plugin extensions are likely to use internal methods regardless, so I don't think we hurt ourselves there.
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="gmail_quote"><div>
* When is it ok to refactor a plugin, renaming any number of "internal" methods?
</div></div></blockquote><div>
Anytime we want, but as you've pointed out, it has to be clear that they are internal.
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote"><div>* As a plugin is being written, and before the documentation is completed, or as a plugin is being rewritten, and before the documentation has been updated, how is a developer to know which parts of the plugin are internal implementation details, and what is part of the public supported API?
</div></div></blockquote><div>
agree that would be a problem
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote">
<div>
I think something more than lack of documentation is needed, to draw a line between internal implementation details, and a public supported API. Otherwise every method written and reviewed needs scrutiny as if it's a public method, because at any point it could be, just by enough people using it. We have a hard enough time ensuring backward compatibility with our public supported documented API.
</div></div></blockquote><div>
agreed
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote"><div>
The only way I could see this working is if every method had full test coverage, not just the public and documented ones. Since we're far from full coverage for even our public documented API methods, I don't think we can yet consider opening up all our methods to be more or less public, even if undocumented.
</div></div></blockquote><div>
agreed
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote"><div>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">By doing so, we enable unintended usage, which is important for emergent design: We can't anticipate how a component will be used like, so its good to observer and learn.
</blockquote></div><div>
"We can't anticipate how a component will be used" is exactly the reason internals should be internal and before things are made public they need a higher level of scrutiny.
</div>
</div></blockquote><div>
I actually agree with both sides here. The important factor is the audience. The general audience won't know any better and should be protected against using a component in a manner other than what we've documented. Advanced users (people who are actually developers), should have the ability to use a plugin how they want, accepting the risks. However, they already have this power, so perhaps no change is necessary.
 
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div class="gmail_quote"><div class="im"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
We also maintain the current style of public APIs simply by documenting only public methods, or those intended for general use. If it turns out that a undocumented method is actually quite useful, its easy to add to the API, simply by documentating it. Today we'd have to rename the method.
</blockquote></div><div>
Crossing that API boundary is more than simply removing the underscore. It's deciding whether it should be exposed, how, whether the name is right, whether it's consistent with the plugin, with other plugins, what the behavior is, what the behavior should be, etc. By having no room for internal things to stay internal, this burden will have to shouldered up-front, as every part of each plugin is written and maintained. That certainly could be done, but it would be a big change. I'm not sure it's worth the cost.
</div></div></blockquote><div>
Keeping with the idea that simpler is better, I'd prefer any route that reduces our public API as much as possible while maintaining ease of use and flexibility.
</div></div>

--

I havent yet had the chance to examine the line provided by Jörn
earlier in this conversation, but I can second the experimentation
with a more open approach, while maintaining the current state of
things.

<div class="gmail_quote">On Wed, Dec 16, 2009 at 4:20 AM, Jörn Zaefferer <span dir="ltr"><<a href="mailto:joern.zaefferer@googlemail.com">joern.zaefferer@googlemail.com</a>></span> wrote:
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
There is a conflict between "safe" and "open" API exploration. Both have their merits. How about keeping private methods as they are, while experimenting with a more open approach in the new widgets?<font color="#888888"></font>
</blockquote><div>
Can you elaborate on what a more open approach would be?
</div></div>

--

Just what was suggested in this thread, but only applied to new widgets. Looking at autocomplete, every single method there could be useful as a public method.
Jörn

<div class="gmail_quote">On Wed, Dec 16, 2009 at 9:06 AM, Jörn Zaefferer <span dir="ltr"><<a href="mailto:joern.zaefferer@googlemail.com">joern.zaefferer@googlemail.com</a>></span> wrote:
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Just what was suggested in this thread, but only applied to new widgets. Looking at autocomplete, every single method there could be useful as a public method.
</blockquote></div>
I wouldn't want to apply different standards to plugins simply based on time of release. If it makes sense to expose every method of autocomplete, we can discuss that, but I think we should apply the same criteria to all plugins.

--

Ok, makes sense. Then we need to go through the new widgets at some point and decide which methods should be private. Currently everything not listed in the specification...
Jörn

One option not considered here is to keep the underscore syntax for
internal methods, but allow external access to them. This provides
users with all the power that Jorn is requesting, while still makes it
clear which are internal methods. Developers would be warned that
using internal methods is not supported, ie, "use at your own risk".
This would cause them to think twice before using an underscored/
private method in their code.
Perhaps some type of flag could be set via the widget factory that
disables the normal 'blocking' of underscored methods. This way the
*default* widget functionality would be to protect internal methods,
as it is now, but advanced developers could specifically set an option
to allow access. This forces a conscience effort on their part.
All of this requires just a few tweaks to the widget factory. No
changes to individual widgets is required.
Just a little gist for the mill.
/Kevin

I can dig that. I like Kevin's suggestions.

A flag would be overkill, but keeping the underscore-warning-sign while removing the code that prevents the call seems like a good compromise. Andrew likes it, Richard?
Jörn

I'm in favor of the flag that Kevin suggested. I think it's a great option.

I don't like it, because it's still punching a hole in the API. These methods are already accessible to the advanced user, and it means seeing this
  var dlg = $('#id').data('dialog'); // accessing internal plugin instance UNSUPPORTED
  dlg._open(); // calling _method on internal plugin instance UNSUPPORTED
// or
  $('#id').data('dialog')._open(); // calling _method on internal plugin instance UNSUPPORTED
instead of this
  $('#myDialog').dialog('_open'); // calling the _open method - what an ugly name
That last example is far too much like
  $('#myDialog').dialog('open'); // calling the open method - what a nice name
to alert the average user that they're venturing into unsupported land. Why? Because they're using the jQuery UI API to call that method. They might well assume it's undocumented or advanced. But since they're walking in the front door, the _ is not sufficient to say 'internal'. The API teaches them how to call methods - pass the name of the method as the first string argument to .widgetname(). If they're going through the API, they shouldn't be able to call things not supported by the API. If there're going beyond the API, they should know they're doing that - having to use .data('widgetname') to access the plugin instance ensures that - and still have the underscore prefix warning.
In short, I don't think we should expose things we don't want exposed. Keep internal things internal. If you want to call something on the inside, you have to come inside first.
- Richard

As far as positions on this go, mine falls in line with Richard's. But
if we're to change this I like Kevin's best.
I'm not really contributing to more discussion because Richard and
Kevin have pretty much covered it imho and I would just be restating.

On Thu, Dec 17, 2009 at 2:31 PM, Richard D. Worth <span dir="ltr"><<a href="mailto:rdworth@gmail.com">rdworth@gmail.com</a>></span> wrote: