Documentation creates contract, which is why you need to be very careful what you document

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

Actually, that picture explains why it isn't documented.

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 pixels from the right-hand edge of the window, and that the buttons are exactly SM_CX­SIZE pixels wide, with exactly SM_CX­EDGE pixels of padding between the buttons, and the buttons are exactly SM_CY­SIZE pixels tall, with SM_CY­EDGE pixels between the top of the button and the top of the window.

Once that picture existed in the documentation, the picture you linked to could never exist.

The picture from Windows 2000 doesn't include the SM_CX­PADDED­BORDER or the the SM_CY­PADDED­BORDER. 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), because that would break existing code.

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 pixels, move left move down SM_CX­FRAME + 1 pixels, and click there, and it will hit the button."

And then Windows Vista shows up, adds some SM_CX­PADDED­BORDER between the Close button and the right edge, and the program stops working.

Publishing the redlines 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.

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.

Comments (40)
  1. Joshua says:

    Wow talk about asking for a bad reason. The reason I wanted similar diagrams was not to define the screen layout but to define the constants. A mysterious 1,3, etc. in the form layout code is a recipe for trouble on Windows next.

  2. sehe says:

    CAUTION: This image is really useful and I wish all of this was actually documented." – I get a big fat malware warning on that site. No-view.

  3. Cesar says:

    It's a pity you can't have both an official "this is what is guaranteed" documentation and an unofficial "this is how it's currently done" documentation (because you know people are going to treat the later as if it was the former, causing endless headaches).

    For open source software, the official documentation is the documentation itself and the unofficial documentation is the source code and its non-documentation comments. I imagine it's the same for Windows, but with only Microsoft employees being allowed to look into the source code.

  4. John Ludlow says:


    And where do blogs like this one fit in? I'd argue the latter, since it's just someone who wants to provide potentially useful and / or interesting information through an unofficial channel. I think somewhere there's a disclaimer that effectively says that a blog isn't to be taken as gospel.

  5. AS says:

    Just reminds me of how beautiful the Aero window decorations were. IMO, still the best desktop theme there ever was.

    I don't understand why they had to go in 8/10, looked much better than the ugly flat look with its Win 3.1 color scheme. (Battery concerns are void because 7 could already disable transparency for battery only)

    I guess we have the fruit company to blame for that general trend, but it's really a shame I now have to guess what's a UI element and what is just static.

    At least under the hood things are now rock solid, so I'll have to live with bad UI rather than switching to an inferior OS (with also bad UI).

  6. BJC says:

    How does this compare to the MS published UI Design Guidelines?

    As I understand it, the UI guidelines address many areas to try to define a consistent user experience. For example, they include recommendations that describe how controls should be spaced on different windows (e.g. dialogs). They also state the default font that should be used for many window elements. The current default font is now Segoe UI but that changed at some Windows version (Vista?). It seems that those guidelines change/evolve with different versions of Windows.

    I'm not sure I understand why there can't also be guidelines for defining the drawing of the window frames, even thought that may change and evolve with different versions of Windows. As was stated, drawing the frames according to a guideline doesn't break anything it simply looks dated. That doesn't seem to be a reason to leave the description of the windows frame undocumentated, for a given Windows version.

  7. skSdnW says:

    It is not about programmatically clicking something, it's about custom/owner draw. The listview uses magic padding constants etc so it is hard to perfectly replicate. Lets even forget about the padding for a second and ask, what is the color of the listview gridlines? You could just have a document that describes the colors and metrics of the v5 common controls. This would be extremely useful to the developer community even though most people are using v6 now and maybe moving to WinRT.

    Every web browser seems to draw their own titlebar these days so if documentation is a no-go, maybe a SDK sample would be possible so people have a better chance of getting it right.

  8. Anon says:


    On… That's the worst false-positive I've ever heard of.

  9. Anon says:


    I don't understand. Who is using comctl v5 in 2015, and why isn't anyone telling them to stop it?

  10. R says:

    On the other hand, not providing certain system metrics encourages people to use magic numbers instead.  When I was writing Windows controls for a project, the reference library frequently provided insight on layout issues that I had.  However, it's full of stuff like "Windows calculates the height as the font plus 2px on top and 1px on bottom."  I think more functions like GetComboBoxInfo(), which tell where components are without the details of inner/outer padding/margins would help cut down on requests for metrics like those in the linked image.  (I was auto-sizing an owner-drawn control and just needed to know how much space to allocate outside of the rectangle that my items occupied.)

  11. skSdnW says:

    @Anon: The issue is owner draw and/or custom controls. If someone needs a TreeListView hybrid control (Process Explorer etc) then v5 documentation would be a good starting point, certainly much better than using "3 + (GSM(SM_CYEDGE) * 2) + magicpadding" and hoping for the best…

  12. John says:

    Usually when a developer asks for this type of information they're doing something I don't care for (changing the Visual Style by trying to mimic an existing one), terrible software, they need to be named and shamed, they prevent us from moving forward to better Windows Versions.

  13. waleri says:

    I'm under the impression, that this image simply visualize what is already documented anyway, so what's the problem adding it to the documentation? A picture is worth a thousands words.

  14. Mordachai says:

    Personally, I despise the idea that this can't be done.  It certainly can.

    There are many ways to handle this:

    a) so what if software "breaks" – that's their problem for taking the documentation as if it were going to be for all time.  No OS is set in stone, nothing stops MS from changing things over time (which they do anyway).

    b) without getting into a time-machine discussion, implement a "visual version number desired" with flags to say that your software makes no assumptions on visual layout, and should use the latest flavor.  If someone wants to use the metrics for Windows 8.1, then they can "lock" their software to that visual metric by saying so in the manifest.

    c) implement new API or IDs for each version of the OS – so if you want to change things for Windows 9 – then add a new API for asking about the layout – or add new SM_XXX symbols for the "windows 9" values.

    I personally am not a fan of the "if you don't document it then nobody can rely on it" line of thinking.  All it does is cause folks to spend time reverse-engineering it, and they still end up dependent upon it.  Maybe they have more reason to think it is their own responsibility – but really – updating software to the latest visual flavor already requires effort at each release, so why would this be any different?

    Too much backwards compatibility code… argument could / should be countered with "you've already written it – just put that flavor in a separate DLL and related functions, and then load that library in association with the target software's manifest".  Again… fairly minor amount of upkeep.

    …and arguments going as far back as Windows 95's UI expansion: yeesh – we've had the same basic layout for 20 years now… I think if MS seriously changed much of anything it would break 100 things anyway, so documenting and supporting it in a more formal, clear, documented way still seems like a win-win.

  15. Joshua says:

    @Steve Wolf: When you wrote down "the metrics for Windows" you made an error like what perpetuates the problem. I don't know how, but I've managed to change those metrics, and it can't be a gross hack because it spreads through saved and restored themes.

  16. Mordachai says:

    @Joshua – There are I assume values stored in themes – values that control the placement / size / spacing / etc. of visual elements.  These values adhere to some internal published or not interfaces that the theme manager uses to draw things, or that is referenced by correctly written controls supplied by MS.

    That the value of SM_CXBUTTON can change isn't the issue.  That you can load a theme that alters the value of that metric isn't the issue.  That's perfectly reasonable, and would be handled neat as a pin by documenting "use CXBUTTON here in exactly this way for Windows 8.1".

    What is at issue is only that SM_CXBUTTON may no longer be used in the same way in Windows .Next.  But so what is my point…

    Everything changes – software must adapt.  By formalizing what the relationship is between a full API for a given OS release only clarifies the situation: in no way does it make things worse; unless you really think that by not-documenting it you actually make the situation better (as oppossed to simply engineering yourself an politically correct "out" of responsibility card while in actuality still making things a mess both for your programmers and your customers who still actually in reality have to deal with the bigger mess that results from lack of contractual documentation – even if that contract is "here is the values for Windows version X – which may change in version Y and beyond… use at own risk)

  17. Daniel Neely says:


    It's probably an indication of a site wide warning; and considering how much of the web scrapes, I'd be astounded if their malware filters didn't occasionally spring a leak and at least temporarily mirror something dangerous somewhere on the site.

  18. Jesse says:

    > "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 pixels, move left move down SM_CX­FRAME + 1 pixels, and click there, and it will hit the button."

    Presumably "they" had a rationally considered, well though-out reason for wanting such a thing, but if *that* doesn't raise a stonkin' big red flag and sound a warning klaxon that you may be Doing It Wrong(tm), I don't know what will.

  19. John says:


    I take it you've never been in a work place where arguments against poor programming practices, such as hard coding the programatic calculation of the position of a close button, comes down to whomever can find the MSDN Documentation that says its a particular way.

    The problem is you've got an official source that *looks* like it might be giving you a contractual guarantee when in reality you have nothing of the sort.

    The bigger problem is that this isn't realized until the next version of Windows rolls around and management is furious that this programatic calculation no longer works. The Programmer is in CYA mode and blames the MSDN.

    The only safe play is to not document stuff like this to not give these poor practices an out.

    This is probably one of the more extreme cases, but one that comes up all the time is printing from services, it has never been documented to work, but enough people have found *evidence* through MSDN to hack together something really zombie-ish and get irate (at Microsoft no less) when it breaks (use your favorite search engine to search "Printing from a Service" for great examples of this).

  20. Kurt says:

    When you have as many developers hacking on your API like Microsoft does, trying to hide details like these doesn't seem like the right approach to me.  Ignorant programmers attempting to do stupid things are going to achieve it whether or not you help them with a diagram.  A better approach is to try to make your readers a bit less ignorant about the sort of things that might change, by clearly stating what is not contractual.  Can't do anything about them being stupid.

  21. Kevin says:

    @AS: It seems everything old is new again……/199589.aspx

    Old… new… someone should name a blog after that or something.

  22. AndyCadley says:

    @Steve Wolf: But you've missed the point. How would you have documented SM_CX­PADDED­BORDER for Windows 95, when padded borders weren't even a thing? If you don't, then you've given people the impression of following the rules but pulled the rug out from under them. And it'll be their customers telling everyone "Don't upgrade to Windows v.Next, it breaks all your programs"

  23. waleri says:


    That's why I am confused – things like SM_CXEDGE and SM_CXSIZE *are* documented anyway, aren't they?

  24. Kirillenseer says:

    The better way is IMHO still just using the system title bar. This way, my app will always look consistent. And quite frankly, I assume that MS debug their title bars way more thoroughly, than I ever could.

  25. 640k says:

    @John Ludlow: And where do blogs like this one fit in?

    –> Since oct 2001 I trust info on this blog more than msdn library. Of course, Raymond tries to spin much information in good light for his employer though.

    @John: Usually when a developer asks for this type of information they're doing something I don't care for (changing the Visual Style by trying to mimic an existing one), terrible software, they need to be named and shamed.

    –> Instead, Raymond works full time creating back compat shims because he thinks it's constructive. What that does instead is developers relying on shims. Windows almost guarantee sloppy developers can continue to develop buggy programs without care. Lesson learned.

  26. GDwarf says:

    @640k: You'd rather no new version of Windows exist because Microsoft has gone under due to no one being willing to upgrade because 50% of their key applications no longer work? (You use hyperbole, I use hyperbole. :P)

    Vista is an excellent demonstration of what happens when Microsoft follows your advice: suddenly basic hardware stops working because the developers have been writing drivers wrong for years. Lots of common hardware never gets proper drivers made, leading to a slow, unstable, and buggy experience for many people. Who gets the blame? Microsoft. Whose sales suffer? Microsoft's.

    There's part of me that does agree with you: Full-time developers should learn how to write code properly, and it's ridiculous that scores of much more talented programmers have to spend their time fixing the mistakes of the ones who simply don't care, but short of Microsoft setting up an iOS-esque "walled garden" (which I'm very opposed to) there's no real solution that isn't worse for end-users, and end-users are the people that computers are built to work for.

  27. Azarien says:

    "Note that changing the visual layout of the caption does not break programs which draw their own caption bar."

    Soon we'll forget how the default caption bar looks like. Every application wants to have a custom bar. Even Visual Studio.

  28. Joshua says:

    @GDwarf: That's why I said publish a broken list that includes the nature of the driver misbehavior that caused the problem. Truth is an absolute defense against libel.

  29. GDwarf says:

    @Joshua: And how many people would read such a list? How many hardware developers would sue as soon as they appeared on it? How do you curate such a list? How does Microsoft monitor every single driver ever written? How bad must a bug be before a driver gets on that list? How many people would simply see it as Microsoft blaming others for their own mistakes?

    I mean, loads of PC users don't even install Windows updates, how do you get such people to not blame Windows when their motherboard has a buggy driver?

    [What happens if a driver gets put on the list, and then it turns out it wasn't the driver's fault after all? -Raymond]
  30. cheong00 says:

    Just wondering if the documentation team had considered introducing a section of non-contractual appendix, where every pieces in it has boilerplate "this section contains implementation detail / illustration to give you better understanding on the topic, however this is subject to change between versions".

    It'll also help to create footprint on how a particular feature changed across version.

  31. Adam Piggott says:

    @anon re: malware warning

    "On… That's the worst false-positive I've ever heard of."

    I have come across several phishing sites hosted by that had been active for some weeks. (Yes, I reported them and they were taken down.) They were not part of the WayBack Machine, they were simply hiding in various corners of the service. Just because they're big, well-known and benevolent, doesn't make them invulnerable :-)

  32. Anon says:

    @Steve Wolf

    "just put that flavor in a separate DLL and related functions, and then load that library in association with the target software's manifest"

    And then spend 100s of hours testing to ensure that loading this DLL doesn't somehow end up stomping the new function at the wrong time.

  33. Nick says:

    @Steve Wolf: You must be new here. "Our software worked fine until Microsoft 'upgraded' Windows. Don't update Windows, keep using [9X/XP/7/IE6]."

  34. Mordachai says:

    Wow, it's intense how little ability there seems to be in the programming community (as represented on this site) for documenting interfaces… like is done for hundreds of other interfaces, which then sometimes have to be superseded in Windows Next and SxS is used to handle… oh, I dunno, exactly this same sorts of things.

    lol – Andy – you've missed the point.  For a future version, you document what that future version uses, how it lays things out, what metrics it needs.  You don't go backwards in time and break the Windows 95 layout API – you keep it too.  and for those apps which say "I use Windows 95 visual layout" – they use the Win95Theme.dll – so that they continue to work & can continue to rely on the _documented_ layout that Win95 adheres to.

    …and since Windows 95 is intentionally a stupid thing to bring up (because it is already water under the bridge – can't go back in time and all that), you start doing this now, for windows 9, and going forward.  Or maybe you back-port it to Windows 8 and above… which MS is perfectly capable of doing and has done with many interfaces in the past (back porting Wind32s, back-porting various APIs via common controls dialog, etc., etc., etc., ad naseum).

    …not rocket science.  Yes, it adds some testing & maintenance debt to each release… which means at some point they have to sunset support for former themes – such as deciding that in Windows 10, Windows 8 theme / layout will no longer be supported (apps that rely upon it will be forced to use Windows 9 theme, and will look funny until you update them).

    …almost like what they do anyway with things like XP and Vista and 2000 and every other thing that – although DOCUMENTED – still eventually becomes unsupported and… yet… the world yet spins, MS is still profitable at last check… and most software continues to function well enough… and supported software continues to be maintained & updated for newer OS versions … like on every other day of the week since the dawn of Windows.

    Seriously… how is this a difficult concept since you're all steeped in it daily anyway?

    [It's more than just "look funny". They may stop working outright. For example, they may not hit-test correctly. And woe unto you if you try to automate another application via coordinate calculations. (Your app uses the Windows 8 metrics, but the other app is using Windows 9 metrics.) -Raymond]
  35. Alex Cohn says:

    @Nick: "Don't update Windows, keep using [9X/XP/7/IE6]." – not anymore!…/Windows-10-will-be-final-version-of-Windows.html

  36. AndyCadley says:

    @Steve Wolf: And when the app that says "I use Windows 95 visual layout" tried to use that information to automate Explorer windows?

    Not to mention how many people complain already that Windows has old dialogs. Can you even begin to imagine what a mess it would start to look like if you mixed and matched the themes for various different versions of Windows on a single desktop.

  37. John says:


    They're documented, but their implementation (IE their exact values) are not. Perhaps I misunderstood here, but I think what's being argued for here is a contractual guarantee that X+Y=Z, metrics that are all free to change from Windows version to Windows version, that is a terrible idea that ensures you're never able to change.


    >Instead, Raymond works full time creating back compat shims because he thinks it's constructive.

    Its incredibly constructive because it means that companies that upgrade are not punished for poor programming practices and encourages upgrades. While I like to believe in the perfect world to, the business reality is that if none of the old crappy software runs on your platform people (more so multi-million dollar businesses) aren't going to upgrade, which means you're out of business real quick. I agree with almost everything GDwarf had to reply with there.

    @Steve Wolf

    >Wow, it's intense how little ability there seems to be in the programming community (as represented on this site) for documenting interfaces

    Try working on any code base of any decent size (25-30 Million LOC; basically anything beyond a trivial Single Page App) with a decent sized development team (50-75+ employees) and come back and tell me if you have the same opinion. Look at these companies internally and how many of them can't seem to document their own internal systems, now multiply that by several orders of magnitude and you're in Microsoft's shoes.

    Dependency Hell is real, as is Servicing Hell, there have been several attempts to fix it the latest one seems to say "Throw everything in the trash, every time, and just roll a single version; Don't like it? Tough Cookie". A profitable company whose name is a fruit seems to have taken this approach. Time will tell if this is the solution that wins out in the end.

  38. Mordachai says:

    Hit testing via display coordinate computation?  Really?  That's a valid approach to anything?  Why wouldn't I walk the child windows looking for the one with the correct ID, then clicking the center of that?

    Such a counter example sounds like a hackity hack hack, not a valid reason to avoid documenting visual layouts.

    I've written an awful lot of Windows software over the years, and I've never automated other software by computing a click-position.  Software which does that sort of hackery deserves to fail.  That's why automation interfaces exist.  If the target software doesn't support automation – then you have no business trying to do this anyway.  And if you do anyway – well, of _course_ it breaks.  Duh.

    If you clearly document something – the it is only that much easier to document the next something: you have prior art to refer to, and you only need update that which has actually changed.  Big companies 30 million lines of code blah – who cares?  Microsoft surely has deep enough pockets to document its UI.  And I would bet that their own software would actually run better – because their own programmers would suddenly have correct information that could be relied upon, instead of winging it and hoping.

    After all… does anyone think that the lack of documentation reduces those who do all of these hackity hack horrible things?  I think not.  I think all it does is make a murkier situation that much darker and less reliable.

    Also – if you see that there is an unmet need that is being hacked at to achieve it – then that is a strong indication that you need a real solution that itself is documented that addresses the actual problem so that folks don't keep having to hack bad fragile / broken solutions to it, eh?

    [News flash: Apps use hackity hack hacks. Also, while declaring that a customer's line of business application "deserves to fail" may win you points in certain circles, it will also lose you a customer. -Raymond]
  39. Henri Hein says:

    @Steve Wolf,

    Backwards compatibility isn't hard, developers handle versioning management "neat as a pin," and I should not use hit-testing?  This all sounds strange in my ears.

  40. anonymouscommenter says:

    Looks like some people believe that old software is no longer sold and its failure would affect only those few using it like big corporations. Not even wrong……/364810

    Yes, publishers built entire new model based on rereleasing old games with zero changes (as they were released + some optional patches) today. No compatibility updates, no bugfixes, nothing. (DirectX 7 in example I posted, in others you can find DX 6; maybe there is even DX 2 game…) Business model based on Microsoft's work on backwards compatibility. (And customers even defend that)

Comments are closed.

Skip to main content