Bernard Marcelly wrote: > Message de Matthias B. date 2009-05-12 11:06 : >> On Mon, May 11, 2009 at 10:56 AM, Mathias Bauer <[email protected]> wrote: >>> For the time being we had to keep "OnLoad" for compatibility reasons >>> (both for registering as well as for sending), but the documentation >>> would be changed to suggest "OnOpen" instead. This can be changed (and >>> perhaps will be changed) in the first release that allows for >>> incompatible API changes (I assume this will be 4.0). >>> >>> Alternatively, we can stay with "OnLoad" until the incompatible change >>> and then switch to "OnOpen" without any intermediate compatibility >>> arrangements. >>> >>> Comments, anyone? >> >> That you even consider removing this event is exactly the lack of >> commitment to compatibility I have critized in the long thread about >> OOo quality recently. There is ONLY ONE acceptable solution for >> changing the name. >> >> - introduce the new event name >> - keep the old event name for compatibility FOR ALL ETERNITY. >> >> It is NOT acceptable to retire it with OOo 4.0! NOT acceptable to >> retire it with OOo 5.0. >> People build their businesses on OOo. Your petty interests in language >> aesthetics are irrelevant! >> If you are worried about the overhead of sending the same event twice, >> well, there's also this option: >> >> - Live with the bad name, compensate it with good documentation and >> then find something more productive to waste your time on than >> breaking existing code. >> >> Matthias > > I totally agree with the opinion and arguments of Matthias B. > There are many cases of unfortunate names in the API, this is not a good > reason > to change the API. Having a correct description in the documentation is > enough.
The best documentation is an API that doesn't need one. This deals with the fact that people don't like to read documentation. Having "speaking" names for events is a good thing per se, not just some "language aesthetics". So using "OnOpen" for the event that is fired when a document is opened in a window and not confusing "OnLoad" with "OnLoadFinished" definitely is a good idea. I was concerned if having an "OnLoad" doing the same as "OnOpen" can be a problem. My suggestion to remove it later should just be seen in the context that incompatible changes in the API most probably will happen anyway and so this small change wouldn't be such a big problem, but could remove a source of confusion. I'm not determined to do that, that's only the least interesting part of my problem. As you and Matthias mentioned it, a short comment about incompatible API changes. I have mixed feelings wrt. this and I hope that developers will do that only in rare and justified cases, e.g. when an API is not or barely usable ATM. And I hope that most changes will cause nothing more than a recompile of the client code using it. But that's only me and I know that there are other people with other opinions. As we also have agreed on discussing all API changes in the public, I hope that not only API developers but also API users will join these discussions. If people refrain from shouting at others and using insinuations about the motives behind suggested changes I'm confident that these discussions will show us where we can allow for changes and where we better don't do it. > It would be more useful to spend time on improving the API documentation (IDL > and Developer's Guide) and correcting known API issues. > Some examples: > API doc : issues 67088, 79943 > API : issues 22625, 64800, 93716 Sure. But I think documentation can be done by anybody knowing about the API, developers as well as users. So you are also invited to do that. :-) Regards, Mathias -- Mathias Bauer (mba) - Project Lead OpenOffice.org Writer OpenOffice.org Engineering at Sun: http://blogs.sun.com/GullFOSS Please don't reply to "[email protected]". I use it for the OOo lists and only rarely read other mails sent to it. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
