{"id":110037,"date":"2024-07-24T07:00:00","date_gmt":"2024-07-24T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=110037"},"modified":"2024-07-31T13:54:29","modified_gmt":"2024-07-31T20:54:29","slug":"20240724-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20240724-00\/?p=110037","title":{"rendered":"API naming principle: If there is no direct object, then the direct object is the source object"},"content":{"rendered":"<p>It is a common practice that method names begin with a verb: <code>widget.<wbr \/><span style=\"border: solid 1px currentcolor;\">Toggle<\/span>()<\/code>, <code>widget.<wbr \/><span style=\"border: solid 1px currentcolor;\">Set<\/span>\u00adColor()<\/code>, <code>widget.<wbr \/><span style=\"border: solid 1px currentcolor;\">Get<\/span>\u00adAssociated\u00adDoodad()<\/code>.<\/p>\n<p>Often, the verb is followed by a direct object: <code>widget.<wbr \/>Set\u00ad<span style=\"border: solid 1px currentcolor;\">Color<\/span>()<\/code>, <code>widget.<wbr \/>Get\u00ad<span style=\"border: solid 1px currentcolor;\">Associated\u00adDoodad<\/span>()<\/code>. The direct object is the thing that the verb operates on or produces. In the case of <code>Set\u00adColor<\/code>, it is setting the color. In the case of <code>Get\u00adAssociated\u00adDoodad<\/code> it is getting the associated doodad.<\/p>\n<p>Sometimes, the verb is not followed by a direct object at all, such as the <code>widget.<wbr \/>Toggle()<\/code> method above. In that case, the direct object is the source object: The widget. In the above example, <code>widget.<wbr \/>Toggle()<\/code> toggles the <code>widget<\/code>.<\/p>\n<p>All of this may sound obvious, but it&#8217;s easy to lose sight of this principle.<\/p>\n<p>For example, a team proposed an API with a <code>Widget\u00adNotification<\/code> and a method <code>widget\u00adNotification.<wbr \/>Delete()<\/code>. As written, it sounds like this deletes the widget notification itself, but the intention was for this to delete a notification listener. The methods for creating and deleting listeners should be named something like <code>widget\u00adNotification.<wbr \/>Create\u00ad<span style=\"border: solid 1px currentcolor;\">Listener<\/span>()<\/code> and <code>widget\u00adNotification.<wbr \/>Delete\u00ad<span style=\"border: solid 1px currentcolor;\">Listener<\/span>()<\/code>.<\/p>\n<p>As another example, the name of the <code>Application\u00adData\u00adManager.<wbr \/>Create\u00adFor\u00adPackage\u00adFamily<\/code> method doesn&#8217;t say what it&#8217;s creating, so the assumption is that it creates an <code>Application\u00adData\u00adManager<\/code>. But that&#8217;s not what it creates. It actually creates an <code>Application\u00adData<\/code> object. The method should more properly be named <code>Application\u00adData\u00adManager.<wbr \/>Create\u00ad<span style=\"border: solid 1px currentcolor;\">Data<\/span>\u00adFor\u00adPackage\u00adFamily<\/code>.<\/p>\n<p>An exception to this rule is factory objects. The purpose of factory objects is to create things, so a <code>Widget\u00adFactory.<wbr \/>Create()<\/code> method is assumed to create a widget. But I wouldn&#8217;t complain if you called your method <code>Widget\u00adFactory.<wbr \/>Create\u00adWidget()<\/code>, just to be clear about it.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>If you don&#8217;t know what it operates on or produces, then it operates on or produces itself.<\/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-110037","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"<p>If you don&#8217;t know what it operates on or produces, then it operates on or produces itself.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/110037","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=110037"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/110037\/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=110037"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=110037"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=110037"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}