A recurring problem I encounter when reviewing API proposals is that teams tend not to be precise in their use of terminology. This casualness is inevitable when you work with a feature for a long time and develop notational shortcuts, but the people who are learning your API don’t have the same level of familiarity that you do, and shifting terminology tends to create confusion.<\/p>\n
For example, there was an API proposal that included two methods.<\/p>\n
runtimeclass Widget\r\n{\r\n void EnableFilter(WidgetFilter filter);\r\n Boolean AreAnyFiltersApplied();\r\n}\r\n<\/pre>\nThe first method talks about “enabling” but the second talks about “applying”.<\/p>\n
For somebody encountering this API for the first time, the existence of two different terms raises questions. Is enabling a filter the same as applying it? Or are there two steps to making a filter active, first you enable it, then you apply it? (Or do you apply it first, and then enable it?)<\/p>\n
When I asked the team, they said that enabling and applying are two names for the same thing. They internally use both terms to refer to adding filters to a widget.<\/p>\n
I recommended that they not use multiple names for the same concept. This makes it harder to see that the two methods are counterparts to each other. Pick a name and stick with it.<\/p>\n
They chose to use “Enable” throughout, so the second method was renamed to Are\u00adAny\u00adFilters\u00adEnabled()<\/code>.<\/p>\nThis consistency extends beyond method names. If there is a parameter that corresponds to a property, use the same name for both the parameter and the property in order to make the connection clear.<\/p>\n
runtimeclass Widget\r\n{\r\n Widget(String id);\r\n\r\n String Name { get; }\r\n}\r\n<\/pre>\nIn this case, the intention is that the id<\/code> parameter passed to the constructor can be read back by reading the Name<\/code> property. In that case, the parameter and property should either both be called Id<\/code> or both called Name<\/code>.<\/p>\n\/\/ Option 1\r\nruntimeclass Widget\r\n{\r\n Widget(String id<\/span>);\r\n\r\n String Id<\/span> { get; }\r\n}\r\n\r\n\/\/ Option 2\r\nruntimeclass Widget\r\n{\r\n Widget(String name<\/span>);\r\n\r\n String Name<\/span> { get; }\r\n}\r\n<\/pre>\n","protected":false},"excerpt":{"rendered":"It may be obvious to you, but that’s because you wrote it.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-111415","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
It may be obvious to you, but that’s because you wrote it.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/111415","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=111415"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/111415\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=111415"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=111415"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=111415"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}