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

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?"

I have an idea for the style guide

[Anonymous Coward]

How about, when naming variables, you have to put the first letter of the typename in the start of the variable name!

And then later let's change the types in the API but keep the unmatching old names for compatibility!

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.

Re:I have an idea for the style guide

[maxwell demon]

How about, when naming variables, you have to put the first letter of the typename in the start of the variable name!

Hungarian notation isn't about using the typename at all.

Please tell that to Microsoft.

Re:I have an idea for the style guide

[Rinikusu]

There were a lot of who went through college in the early-mid 90s where Hungarian notation was considered proper software development and scores were marked down in various programming classes if you didn't adhere to it. It was the late-90s/early-2000s when people apparently discovered that it was a very, very bad idea especially as we refactored 5-10 year old code. Now it seems we're happy if you just use camel-case.

Re:I have an idea for the style guide

[NevarMore]

I was (am?) the generation who learned to code in the mid-90s. I hate to sound lazy, but once we got over that hungarian nonsense, every team I've worked on just agreed (or had dictated) an autoformatter for our IDE and just made sure to run it before we committed. Hell one team had it setup as a pre-commit hook in SVN. It mooted many of the style arguments and let us focus on solving real problems.

Hell the more modern IDEs like Eclipse, IntelliJ, and VisualStudio even suggest variable names and hint for proper case. As programmers and software engineers should we not use software tools to do tedious and mundane work for us?

Re:I have an idea for the style guide

[TheRaven64]

The third explanation in this thread, and not the correct one either.

Originally, Hungarian notation was used by the Apps group in Microsoft. It was used to indicate things that were not expressed in the C type system. For example, an integer referring to a column number in a spreadsheet would be colsFoo, while another referring to a row would be rowsFoo. If you wrote something like if (rowCurrent When the Systems group adopted the convention, they started using it for the variable type, not its meaning. This completely defeated the point, but the Systems group version was the one that caught on due to their greater influence within the company.

C is one of the few Algol-family languages where this is actually necessary. In most others, you can create a columns type and a rows type that are both integers but can not be implicitly cast to the other.

Rude words

[madprof]

Obviously they do have to put in the bit about not using words that some might find offensive in case someone, having a bad day, put it in and they had no come back.
It's quite incredible what some developers, at any size of company, will do sometimes.

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.'

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.

[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...)

Bad title

[PCM2]

I just want to go on record as saying I hate this headline. I didn't pick it. Furthermore, I don't think there's anything in particular about Microsoft developers that makes them "need a style guide" more than anybody else, and that notion had absolutely nothing to do with my column. I just thought it was interesting that a Microsoft style guide exists, that it's available for sale, and that it has some interesting stuff in it about writing for software UIs that a lot of developers probably don't think about. That's about it.

Re:Bad title

[gbjbaanb]

It's the best way to encourage consistency across applications and the accompanying documentation. Does that not happen anymore?

no, it doesn't happen anymore. The original style guide was good - it said how much space to leave around the edges of dialogs, how big to make buttons and where to put the ok/cancel buttons. the end result was an overall look and feel that made sense no matter which application you used, and that meant TCO was reduced as users knew how to use it.

Fast forward to the XAML/WPF/C# era and all that went out the window in favour of "rich" UIs where you have a stupid coloured orb that everyone thinks is decoration until you realise it's the main system menu, and every application has a different set of awful skins.

I would hope (haven't read it) that this redresses the balance.

Master/slave

[Samantha Wright]

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.")

Dear Neil McAllister,

That terminology originally comes from disk drive buses, and the municipality is Los Angeles. Are you really a tech writer?

Sincerely,

Suspicious

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.

Re:Nobody is happy

[19thNervousBreakdown]

Because that way there's only one success, and many failures.

0(false) = success
1(true) = failure
2(true) = different failure
3(true) = yet another failure