API Perfection

You constantly see me making changes in the API design even before I have actually coded them, or even recode an entire component just because of a small change. You might think that I making changes just for the sake of it but there is something much more deep in this. If you look at many other development API's they have a constant problem of not being usable easily. Some use low case letters only which means that you have a real hard time reading your code when it uses function names like gtk_signal_connect or gtk_box_pack_start. C++ API's also have problems that thier class names and methods feel like programmers just added them in one by one without caring for any consistency. Just a look at MSDN .Net classes and you instantly get puzzled. I know that the Screens API is going to have problems of its own (no static type checking since object handles are actually UInt32 typedefs) but I did want the component names and function names to be very consistent and easy to use. I am constantly talking with my Messenger users about function names like should it be CoreListCount or CoreListSize to return the number of items in a list. They sound similar and you would think that Size might be in bytes but then again its a list and when you say the size of the list you mean the number of items, not the size in bytes of the list. Another reason I chose CoreListSize is because it has a 'set' function called CoreListResize which CoreListRecount doesn't work well. Nearly all function names have consistent names like Read/Write, Open/Close, New/Free, Get/Set and you will able to find them across most components. I myself plan to code alot using my API (My API uses itself, a brick on brick design) and I want it to be easy to use and not constantly grabbing some online documentation or book to write some simple code. I want to be able to see the function definition and know how to use it without special notes and warnings like you may only call this after this or that after that. There are times when these are crucial like you need an Open before you do a Read and you should not use a Write after a Close but even then your code wont fail but rather will reopen the stream for read & write use even if you only planned to read from the file which means that any other thread which wants access to that stream will have to wait untill either the thread is released or a Close function releases the stream. But its easier to add in an Open/Close function pair then finding why the application dies when it reaches the Read function. Programmers will be able to be notified of this via thier module blog which is where errors and warnings can be filed to the programmer without interupting the user. Over time I will probably continue to modify function names untill I get them right, but its better I spend time renaming them then programmers spending time being frustrated.