If you have been following the Design Guidelines updates I have done and the Design Guidelines document you will notice we use a pattern…. Nearly every rule begins with “Do”, “Do not”, “Avoid” or “Consider” to provide an instant context in which to read the rule.  But given the vagaries of the English language we are sometimes forced to use somewhat odd wording to accomplish this.    So, the team is debating whether or not we should update the guidelines such that we don’t “force” each rule into that format.  

 

So for example instead of:

     Do prefix interface names with the letter I, to indicate that the type is an interface.

 

We’d have:

 

    Prefix interface names with the letter I, to indicate that the type is an interface.

 

And maybe even more interesting, instead of:

 

    Do use similar names when defining a class/interface pair where the class is a standard implementation of the interface.  The names should differ only by the letter I prefix on the interface name.

 

We’d have:

 

    When defining a class/interface pair where the class is a standard implementation of the interface, the names should differ only by the letter I prefix on the interface name.

 

Thoughts?  Which style do you think works best?