Why Microsoft Developers Need a Style Guide

snydeq writes "What your interface communicates to users can be just as important as what your software does, writes Fatal Exception's Neil McAllister in discussing the latest edition of the 'Microsoft Manual of Style', a style guide aimed at designers and developers who create Microsoft software, as well as those who write about it. 'The gist of much of Microsoft's advice is that a user's relationship with computer software is a unique one, and it's important to craft the language of software UIs accordingly,' McAllister writes. 'Occasionally, Microsoft's recommendations verge on the absurd. For example, you might not think it necessary to admonish developers to "not use slang that may be considered profane or derogatory, such as 'pimp' or 'bitch,'" but apparently it is.'"

Comments

Obviously it is...

[Anonymous Coward]

You silly open source GIMP developers...

Nobody is happy

[Anonymous Coward]

The only intuitive interface is the anus, and even people like goatse mess it up.

Re:Nobody is happy

[TheRaven64]

is that an API does not break "unwritten" conventions like always returning true even when the operation was unsuccessful

Most POSIX APIs return true on error and false on failure. The idea is that this lets you write if (something()) { error_handler(); }. I've no idea why they thought this made more sense than if (!something()), but judging by the rest of UNIX I suspect that they had to type their code in morse with one hand while fighting a tiger with the other, so every character saved could mean the difference between life and death...

When loading a kernel module...

[Anonymous Coward]

Cancel, or "pimp this bitch"

Re:When loading a kernel module...

[flyingsquid]

"It looks like you're trying to write a letter expressing your dissatisfaction with an escort service. Would you like help trying to bitch out this pimp?"

They are bad at naming things.

[Anonymous Coward]

Take the 'Malicious Software Removal Tool' for one example. Sounds to me like a malicious program that goes and removes software from your computer. They should have called it the 'Tool for Removing Malicious Software'. I look at such ambiguity with a laugh. I recently had a dialogue box on my computer saying something along the lines of "Problem Reporting _____". (I forget the exact text.) Does that mean that the system is reporting a problem, or having a problem reporting? Considering that most users of the software are not experts, they should try harder to make things less confusing.

Re:They are bad at naming things.

[Anonymous Coward]

>Take the 'Malicious Software Removal Tool' for one example. Sounds to me like a malicious program that goes and removes software from your computer

Thank you for your bad ass-insight.

Re:They are bad at naming things.

[adjuster]

Reminds me of the short-lived Critical Update Notification Tool Microsoft released back in the early 2000's. (Yeah-- they really named it that, though they _quickly_ backpedaled on the name...)

Re:They are bad at naming things.

[140Mandak262Jamuna]

Take the 'Malicious Software Removal Tool' for one example. Sounds to me like a malicious program that goes and removes software from your computer.

The name accurately describes what the software does and how. Your explanation that it is a malicious tool that removes software is correct. Your mistake is to assume it is a tool to remove malicious software.

Re:They are bad at naming things.

[VortexCortex]

They should have called it the 'Tool for Removing Malicious Software'

I'm sorry, you'll have to take up your grievance with Richard Stallman; Apparently GPLv3 is the only license allowed for derivatives acronyms such as TRMS.

You may scoff, but style is everything

[phonewebcam]

Choose the single leg double-hand overarm for distance.
Or, if you want maximum impact, and hence noise when the chair lands, go for height: a full seat grab upper thrust is your best option.
Then there's the full intimidator, often accompanied with shrieks alluding to colorfully burying someone whilst holding it by two legs high above your head - this move requires two full laps of the office before deployment.

Re:Rude words

[nschubach]

What if you are actually writing software for a pimp or dog breeding?

Re:Rude words

[Samantha Wright]

Then you use neutral terminology, like 'executive-level sex worker' and 'that one secretary who talks too much.'

Re:I have an idea for the style guide

[skids]

I don't know, I found the chapter on EnterpriseInterfaceThunkClassEnterpriseGeneratorCOMParameterInterfaceThunk32 COM_Enterprise_Enterprize_ENTERPRISE very illuminating.

Design patterns: alternate names

[Anonymous Coward]

You may be familiar with design patterns. Those in the know sometimes give them nonstandard names, such as:

• pimp - Define an object that encapsulates how a set of objects interact. Promotes loose coupling by keeping objects from referring to each other explicitly, and it lets you vary their interaction independently.
• bitch - Attach additional responsibilities to an object dynamically keeping the same interface.
• pms - Allow an object to alter its behavior when its internal state changes. The object will appear to change its class.
• company bathroom - Ensure a class has only one instance, and provide a global point of access to it.
• strapon - Convert the interface of a class into another interface clients expect. An adapter lets classes work together that could not otherwise because of incompatible interfaces.
• player - Use sharing to support large numbers of similar objects efficiently.
• dating - Allows concurrent read access to an object, but requires exclusive access for write operations.
• screw - Represent an operation to be performed on the elements of an object structure.
• orgy - Combining multiple observers to force properties in different objects to be synchronized or coordinated in some way.
• "let's not put it on, baby" - Reduce the overhead of acquiring a lock by first testing the locking criterion (the 'lock hint') in an unsafe manner; only if that succeeds does the actual lock proceed. Can be unsafe when implemented in some language/hardware combinations.
• "I love you" - Manages operations that require both a lock to be acquired and a precondition to be satisfied before the operation can be executed.
• divorce - Addresses problems with the asynchronous pattern that occur in multithreaded programs
• alimony - asynchronous interface to resources that must be handled synchronously.

There is a good reason for this...

[wbr1]

...admonish developers to "not use slang that may be considered profane or derogatory, such as 'pimp' or 'bitch,'" but apparently it is.'"

Microsoft does not want their true relationship with their customers to become widely known.

Re:Master/slave

[PPH]

Similarly, the relationship between USB peripherals could be described as "master/slave," but these terms could also be considered offensive. (The "Microsoft Manual of Style" says such language is prohibited in "at least one U.S. municipality.")

Damn! I just finished changing all master/slave references to pimp/bitch. And now they tell me that this won't do either?

How about top/bottom?

Domme/sub?

Ob. scenario:

[Tastecicles]

Clippy: "It looks like you're trying to pimp your presentation. Would you like some help with this?"

Options: "Yes. Show me how to pimp my document!"
  "No, fuck off you annoying little shit!"
  "If I have to turn you off in the options again I'm gonna bitchslap my laptop!"

Re:Bad title

[Froboz23]

I agree that this document should be free rather than for sale. For more details on why I think this document should be free, please refer to my Kindle eBook "Why I think the Microsoft Style Guide Should Be Free", available for download from Amazon for only 99 cents.