Few days back I was going through the usual rounds of some forums I visit now & then and once again I came across more than one post where some poor soul used undocumented API of a library/package to achieve his goals and when the next update came out for the said library/package, his shit broke because the API changed in a stupid way.
What kind of stupid way you might ask. Its the kind of stupid way where you change the visibility of a method to a more restricted one, like changing public to protected or private.
When writing any code, some thought must be put into how to structure it, more so if its a library and/or a package which will be used in multiple projects, by you and/or others. Wingin’ it & botching the API now and then is just plain stupid & insane. While its risky using undocumented API of any library/package, changing visibility to a more restricted one reflects that the developer of the said library/package fell asleep when designing the API. What were the reasons to keep a method/property unrestricted (public) or less restricted (protected) and what has changed which warrants the drastic step of restricting it. Even if you are the only consumer of the said library/package then also it would require you to make a lot of changes everywhere that API has been used; its not something that should be taken with a cavalier attitude.
And then there’s the matter of naming conventions. A lot of developers name methods and properties in similar way irrespective of their visibility. That approach results in code which is at times confusing and can be misleading. Looking at a method or property being used in code somewhere, you have no way of knowing whether its visible (public) or invisible (protected or private). Not to mention that it allows for easy change of visibility which can screw things up down the pipe.
Smart developers follow smart naming conventions, like prefixing an underscore to the name of invisible (protected or private) methods & properties. Anyone taking a look at them then knows what they are, not to mention the fact that it would also make you think before you design your API structure because making a method/property invisible or vice versa would imply you change the names as well.
Good API design means risk free or very low risk API consumption and sanity of everyone involved. If you don’t think before designing your API then you’re just creating a risky venture which would pass on its risks to its consumers.