The runtime styling API’s property names come directly from the style specification, which follows more of a CSS naming tradition that differs in many ways from the Cocoa naming convention iOS and macOS developers are accustomed to. Combined with #5970, this means developers really have no clue what to set many properties to unless they read the SDK’s source code or inspect similar properties’ values in the debugger.

Some examples of poorly named properties, starting with the most severe issues and ending with the most benign ones:

• iconImage – The developer would expect to set this property to a CGImage, NSImage, or UIImage, but definitely not a string. It should be called iconImageName. Even if we fix Add category convenience methods to NSNumber for style values (was: Runtime styling properties are too loosely typed) #5970, developers might expect to pass in a path or URL string to an image, which would fail.
• textFont – The developer would expect to set this property to an NSFont or UIFont, or perhaps an NSFontDescriptor or UIFontDescriptor, but definitely not an array of strings. It should be called textFontNames.
• rasterBrightnessMin and rasterBrightnessMax – Minimum and maximum are always written out, so abbreviating them looks sloppy in Objective-C and Swift.
• circlePitchScale – The developer would expect to set this property to a CGFloat. Maybe this would get better once we fix Add category convenience methods to NSNumber for style values (was: Runtime styling properties are too loosely typed) #5970, but another fix would be to rename this property circlePitchScaleStategy or somesuch.
• lineDasharray – This is called a “dash pattern” in many Cocoa APIs. Swift in particular has moved away from putting types inside symbol names.
• rasterHueRotate – This is a verb, whereas properties should be nouns. This can be a problem in Objective-C, where you can use the same syntax to access a property getter or call a parameter-less method.

On the other hand, as important as it is to ensure consistency with the rest of the SDK and with Cocoa APIs, there’s a strong case to be made for consistency with the style specification and GL JS when it comes to the runtime styling API. We should at least make a few conservative changes (like the first two above) and leave the rest of the API intact.

To rename any property, we’ll need an override mechanism like the one envisioned for documentation in #5954.

/cc @frederoni @jfirebaugh @incanus