{"id":44904,"date":"2015-05-08T07:00:00","date_gmt":"2015-05-08T21:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2015\/05\/08\/documentation-creates-contract-which-is-why-you-need-to-be-very-careful-what-you-document\/"},"modified":"2019-03-13T12:15:19","modified_gmt":"2019-03-13T19:15:19","slug":"20150508-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20150508-00\/?p=44904","title":{"rendered":"Documentation creates contract, which is why you need to be very careful what you document"},"content":{"rendered":"

A person with a rude name asks, “Why does MS not document the system metrics used by classic\/pre-uxtheme windows and common controls<\/a>? This image<\/a> is really useful and I wish all of this was actually documented<\/a>.” <\/p>\n

Actually, that picture explains why it isn’t<\/i> documented. <\/p>\n

Suppose such a picture existed in the Windows 2000 documentation. I don’t know what it would say exactly, so suppose, for the purpose of discussion, that it said that the caption buttons are exactly SM_CX­FRAME<\/code> pixels from the right-hand edge of the window, and that the buttons are exactly SM_CX­SIZE<\/code> pixels wide, with exactly SM_CX­EDGE<\/code> pixels of padding between the buttons, and the buttons are exactly SM_CY­SIZE<\/code> pixels tall, with SM_CY­EDGE<\/code> pixels between the top of the button and the top of the window. <\/p>\n

Once that picture existed in the documentation, the picture you linked to could never exist. <\/p>\n

The picture from Windows 2000 doesn’t include the SM_CX­PADDED­BORDER<\/code> or the the SM_CY­PADDED­BORDER<\/code>. It can’t, because those metrics didn’t exist in Windows 2000. Since the diagram is part of the documentation, it is contractual, and it would not be possible to alter the layout of the window caption (say, by incorporating a new metric like SM_CX­PADDED­BORDER<\/code>), because that would break existing code. <\/p>\n

For example, a program may have looked at the diagram and concluded, “Okay, so if I want to programmatically click the Close button, I can go to the upper right corner of the window, move down SM_CY­FRAME + 1<\/code> pixels, move left move down SM_CX­FRAME + 1<\/code> pixels, and click there, and it will hit the button.” <\/p>\n

And then Windows Vista shows up, adds some SM_CX­PADDED­BORDER<\/code> between the Close button and the right edge, and the program stops working. <\/p>\n

Publishing the redlines<\/a> would force the visual layout to be locked in stone. Windows 95 could not have added the Close button. Windows Vista could not have added extra padding around the buttons. <\/p>\n

Note that changing the visual layout of the caption does not break programs which draw their own caption bar. They will continue to draw the caption bar their own custom way. If they tried to mimic the Windows 2000 caption bar, then they will continue to mimic the Windows 2000 caption bar, even on Windows Vista. But nobody gets hurt, because the application is doing both the drawing and the hit-testing, so it remains in sync with itself. <\/p>\n","protected":false},"excerpt":{"rendered":"

Once it’s documented, it needs to remain supported forever.<\/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":[26],"class_list":["post-44904","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-other"],"acf":[],"blog_post_summary":"

Once it’s documented, it needs to remain supported forever.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44904","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=44904"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44904\/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=44904"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=44904"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=44904"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}