All Code is an API – One Insight on How to Design Good Interfaces in Programming

I was looking through some You Doodle code today and noticed I did something a little odd.

Here is the method in question:

+ (ImageEditorViewController*) showImageEditorWithImage:(UIImage*)image resize:(BOOL)resize isBlank:(BOOL)isBlank aspectRatio:(CGFloat)aspectRatio fillColor:(UIColor*)fillColor editedBlock:(ImageEditedBlock)editedBlock;

This method allows showing a popup view controller in You Doodle that let’s the user crop, flip, rotate and filter an image. The resize parameter is a little confusing and simply indicates whether the image should be pre-processed or not (if it’s too large, downsized or if it’s too small, upsized, etc.). I’ll be renaming that parameter for sure.

In some cases (isBlank = YES), the user can also set the color of the entire image. The fillColor allows tinting the image a different color (used for the frames feature to fill a template frame with a background color or image).

The parameter that I realized was really out of place was the aspectRatio parameter. This requires knowing how to calculate the aspect ratio of your image so that the crop rectangle of the popup image editor is correct. Is it width / height or height / width? What if you pass 0 or a negative number? Twice now I have seen bugs on the App Store with You Doodle where the initial crop rect is wrong and the image stretched funny when changing the background to a different image. It is supposed to show a crop rect that is the same aspect ratio as the current background.

This is a great example of a bad API. The caller needs to know how the internals of the ImageEditorViewController calculate and use the aspect ratio. A better approach that I will be implementing tonight is to instead require an initial crop rect to be passed. Then the internals of the ImageEditorViewController can calculate the correct aspect ratio without burdening the caller of this function with that responsibility.

Remember, all code you write is an API, even if you are the only one working in the code. Make sure the user of your code doesn’t need to know about implementation details of the code.