This is a comprehensive list of many considerations. Top of the list should be to have as small of an API as possible. API is forever. If you expose too much up-front then it increases the surface area of getting things wrong, which developers will be stuck with for a long time or need to deal with eventual deprecations which is fun for no one. Also, more API leads to higher complexity in learning. It is better to see how your API is being used and slowly reveal more functionality as you become confident it is what developers need.
I also believe API should go through a feedback/review processes with peers. Other developers will have used different patterns, have a different base of experience with the platform, and can generally help find common mistakes. So, here's some of my feedback/nitpicks on MGTileMenuController.h :) --
@property (nonatomic, weak, readonly) id<MGTileMenuDelegate> delegate; // must be specified via initializer method.
- (id)initWithDelegate:(id<MGTileMenuDelegate>)theDelegate;
It is very rare for delegates to be required for initialization, and I don't see why the @property for the delegate needs to be readonly? Perhaps an owner would be a better model?
The isVisible property looks like this:
@property (nonatomic, readonly) BOOL isVisible;
But typically for BOOLs the property is the normal form with a specific "is" getter:
@property(nonatomic,readonly,getter=isVisible) BOOL visible;
// N.B. All of the following properties should be set BEFORE displaying the menu.
This makes me wonder what happens if I want to change them later? It seems that they should always be able to be changed, and in general comments shouldn't be required to understand library behavior as they'll just be missed by developers anyways.
Why would the nextPageNumber not be +1 from currentPageNumber? Also, why do I need to supply a currentPageNumber when it appears currentPage is a @property of the class? Is there a difference between "currentPage" and "currentPageNumber" as their naming indicates there might be one? Also, it might be better to name the method similar to the NSIndexSet convention "indexGreaterThanIndex." Should an NSIndexSet actually be used instead?
- (UIBezierPath *)_bezelPath;
This method looks like it is private/internal because of a leading underscore, so it shouldn't be exposed in the header. Also, Apple has reserved naming methods with a leading underscore (especially important when you are subclassing!). https://developer.apple.com/library/mac/#documentation/Cocoa...
In general, if the developer doesn't need the utilities, I highly question adding them to the header since you'll be responsible for them for all time.
Finally, why not add the delegate protocol to the header file so everything is consolidated for the developer using the class?
"API is forever. If you expose too much up-front then it increases the surface area of getting things wrong, which developers will be stuck with for a long time or need to deal with eventual deprecations which is fun for no one. Also, more API leads to higher complexity in learning. It is better to see how your API is being used and slowly reveal more functionality as you become confident it is what developers need."
This is so, so true. If you find yourself thinking about exposing something because someone might have a use case for it or to provide greater control over some very specific corner case, write it down, file it somewhere, and revisit that when you see how people are actually using your API. Don't mistake all the ways your API could be used for all the ways people want to use it.
I also believe API should go through a feedback/review processes with peers. Other developers will have used different patterns, have a different base of experience with the platform, and can generally help find common mistakes. So, here's some of my feedback/nitpicks on MGTileMenuController.h :) --
It is very rare for delegates to be required for initialization, and I don't see why the @property for the delegate needs to be readonly? Perhaps an owner would be a better model?The isVisible property looks like this:
But typically for BOOLs the property is the normal form with a specific "is" getter: This makes me wonder what happens if I want to change them later? It seems that they should always be able to be changed, and in general comments shouldn't be required to understand library behavior as they'll just be missed by developers anyways. Why would the nextPageNumber not be +1 from currentPageNumber? Also, why do I need to supply a currentPageNumber when it appears currentPage is a @property of the class? Is there a difference between "currentPage" and "currentPageNumber" as their naming indicates there might be one? Also, it might be better to name the method similar to the NSIndexSet convention "indexGreaterThanIndex." Should an NSIndexSet actually be used instead? This method looks like it is private/internal because of a leading underscore, so it shouldn't be exposed in the header. Also, Apple has reserved naming methods with a leading underscore (especially important when you are subclassing!). https://developer.apple.com/library/mac/#documentation/Cocoa...In general, if the developer doesn't need the utilities, I highly question adding them to the header since you'll be responsible for them for all time.
Finally, why not add the delegate protocol to the header file so everything is consolidated for the developer using the class?