<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>
--