OpenDocument tells the developer to “Open” the document here.
DocumentOpened, sounds like an async event that would fire when the document has been opened (past tense) and now the main loop can determine if there was a error and display that or display the document.
This kind of crap, is maddening, because it makes it less self-explanatory and just illustrates to experienced programmers that this is a tool to avoid and ridicule.
It’s misguided for sure. The rule that lead to this is that events should be past tense. That’s why we got to Pressed, because it happens after the button has been pushed. This makes sense, but was applied too broadly, because you’re damn right. OpenDocument is the right name, because it’s not that something has happened, but that something should happen.
The genius…
When syntax evolves, devolves or otherwise dissolves. It’s the new-kids-on-the-block that suffer most, as they don’t know why legacy coded solutions in the forum or elsewhere are unusable in the latest release. Thank you @thommcgrath for explaining the philosophy behind the convention.
That reminds me when I came to personal computer (an Apple //c running ProDOS, 1986).
When I started to search examples, all I found (nearly) was DOS 3.3 (the Apple ][ DOS 3.3) examples. Useful; more useful than API3…Std API, but…
This difference is really the heart of my issues with API2. And changes are still being made, by the way. Look through the tracker, and you’ll find cases to have other things renamed. Some more valid than others.
I have never objected to fixing design shortcomings, such as having databases fire exceptions and FolderItem.Child being 1 based. My stance on the issue today remains the same as it did when I was arguing against them within the company back in 2013. Every change needs to have strong reasoning to be acceptable. Renaming Array.Append to Array.Add is an example of a change with little value. Geoff and discussed this one at length, and the argument is that you don’t append something to a shopping list, you add it. That’s a fair argument, but the change needs to be weighed against literal decades of existing code AND the user’s time required to update. It’s a change with zero functional improvement, so it never should have happened. Yes. Add might make more sense in certain contexts, but Xojo doesn’t exist in a vacuum. Existing code is important, and many of these API2 changes just didn’t care about that at all.
In some cases, like DocumentOpened, this is a step backwards. I’m all for considering the temporal state of event names, but this was considered wrong.
Another example I’ve found recently is Xojo: Account Login. Like I said, more changes are coming. In this one, the request has been made to give DesktopTextField a menu-based choice of input types, like the other platforms have. This is not a bad thing at all, but at the moment, there would only be two options: Text and Password. So… why make the change now? Wait until you have another input type to provide a carrot to users to make the change. The request is just busywork for the user right now. The case also requests that the field templates be removed from the library, and I can’t see how these are related. Those are there for convenience, and could be updated for the new change. Why remove them? Is there a desire to remove all the control templates?
Not if you are using an analogy to a paper shopping list… A paper shopping list is in principle unordered. You can write in the top or bottom margins, or even on the sides, or draw a line and start a second second row etc. at any time to add more items.
Append means specifically add at the end.
I have to say it’s annoying that there are separate button types in the library and the names don’t all start with button!
-Karen
We opted not to have the templates apply names because there are lots of different conventions. I’d love if the default button template were to name the button “ActionButton” because that’s what I like to use. But it’s not what you want to use. Better to keep them default just like the regular button.
Regarding the array, I get that point too. Arrays are ordered, but their order often isn’t important. It could just be a set of things, just like a paper list. The paper list is still ordered, it’s just that the order may not matter.
But as the big boss is arguing that Xojo is low code … I wonder how the remaining team can cope with so much non-sense 
I would argue that changing APPEND to ADD then confuses the use of INSERT … isn’t INSERT adding something too? Append infers it will be tacked on the end , Insert infers that it will be “inserted” at a specified location, but ADD is ambigious… Am I adding to the end? the beginning? the middle?
Since they seem to like long names they could have opted for a Objective C style such as: DocumentShouldBeOpened - one should file an Issue for it to be renamed again, just for fun. Their users are now accustomed having to rename things every now and then 
(or just continue using API 1)
Let’s suggest to rename .Add to .AddAtEnd to make it clear (and verbose). .AddAt(pos) should be .InsertAt(pos). And to make it more convenient for their users (and there might even be some use-cases) they could add .InsertInBetween(notBeforePos, notAfterPos) - that would be quite natural and easily understandable, right? 
At least Apple hasn’t fallen in that rabbit hole with Swift… it uses Append() and Insert(at:x)
IIRC, that’s why Geoff came up with AddAt… lol…
The other advantage of using Append and Insert is the easily recognizable difference. Add and AddAt are so close that they can either force you to think, or to use the wrong one and not spot it. This lack of contrast is frustrating in GUI, but to have it in code as well.
I hate method overloading for the same reason.
With a good IDE that won’t happen, as it will show you all avaiable signatures … you’re right that in the green world that won’t happen.
That’s not true anymore. The hint space can show (if I recall correctly) up to 4 signatures now.
Good to see some progress and thanks for the update.
Years ago in REALBasic there was something called the Tips window which showed you all the signatures.
-Karen
If you use verbose function names, auto complete will provide you a list of the possibilities and help you pick the correct one there and then.