Style for the Design Guidelines Document

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?


Comments (29)

  1. Wilco B. says:

    The latter ‘options’ seem more natural to me, hence I find it easier to read. I doubt if the first ones add any value.

  2. Mitch Walker says:

    I agree, the second form makes for easier reading. As long as the point comes across, let’s drop the Do.

  3. Andy Smith says:

    I’ve found that I like a style where the Do/Do Not/Avoid/etc, headings are above or to the left of the rule, in a larger font. This gives you context, without forcing weird wording.

  4. MartinJ says:

    I’d also prefer you leave the do, do not stuff there as a heading. I’d liken it very similar to using "Note:" to indicate some relevant aside.

    Heck, the list would be sortable by the headings. Clear, easy to read writing is prefered over the convoluted ones just to force the initial word.

  5. Daniel Dunbar says:

    For the first two examples, adding another keyword of ‘always’ and replacing the ‘do’ with ‘always’ gives a readable sentence without breaking away from the command form.

    The idea of trying to use consistent language to make the intention more formal and obvious strikes me as a reasonable idea. A useful way to think about it, in my mind, is to consider how each statement would be translated into an algorithm if you were trying to write an automatic style conformance checker.

    Some other formal/keywordish ways to write conditions consistently:

    Every … should be

    No … should be

    Never …

    Unless necessary, never

    If possible, always

  6. In our User Requirements, instead of ‘should’ we shall use the term ‘shall’ 😉

  7. Ihab says:

    I like the Do/Do not approach as well precisely for the reason Brad mentioned. I dont mind that the sentence may be skewed a bit–it still works for me as I’m aware that Im reading a "technical manual" and not a literary piece.

    It also helps with speed reading/searching: when I’m looking for a particular topic to find out if I’m following/violating a guideline, I can immediately focus on its Do’s and Don’t’s rather than reading something like "When defining…". The latter requires a bit more time to convey the meaning of Do or Don’t.

  8. Mark Cidade says:

    I think that the subject (as a noun) should come first. When scanning for a particular thing, I look for that thing, not whether I should do it, nor do I look for the actions I perform on that thing (e.g., defining). Thus, the above should be:

    INTERFACE NAMES should be prefixed with the letter I, to indicate that the type is an interface. EXAMPLE: IFoo


    CLASS/INTERFACE PAIRS, where the class is a standard implementation of the interface, should differ in names only by the letter I prefix. EXAMPLE: Foo and IFoo

  9. Buck Hodges says:

    The great thing about do/don’t is that it is clear that such a statement is a requirement and that consider/avoid encourage but are optional. The phrase "when defining" doesn’t clearly convey the same information.

    Someone mentioned following RFC 2119 ( I think that is a really good suggestion.

    If that’s too dramatic a change, I would favor icons to the left of each statement. The icon could just be Do in bold or it could be a symbol. The document would still convey the same information that it does today but without the awkward need to start each sentence with only one of a handful of words.

  10. Tom Miller says:

    I like the Do/Don’t/Consider/Avoid format that the current guidelines exhibit. It makes them easier to read.

  11. Marco Russo says:

    I like Do/Don’t pattern. Despite occasional grammar inconsistency, it’s very clear to understand the underlying message. May be I’m influenced by the fact that Englis isn’t my native language, but the Do/Don’t pattern is very expressive.

  12. Steve says:

    I also like Do/Dont pattern. It defines when things are ‘requirements’ vs. recommendations.

  13. Joshua Allen says:

    The Do/Don’t pattern is my preference, too. Grammatical elegance is subordinate to clarity of communication. The previous suggestion to use Never/Always is also acceptable, though I see no reason to switch. Finally, if you *do* switch to the pattern of "when doing blah, you should do X" — please don’t underline the part about "when doing blah"; underline the relevant word such as *should* — this is the same pattern used in the RFCs, and allows a user to quickly scan for the keywords MUST, SHOULD, MUST NOT and so on… The RFC technique is also acceptable, but the least attractive of the bunch.

  14. Eric says:

    I really enjoy the current Do/Don’t pattern.

    I don’t mind grouping by headings, but moving to less formal language isn’t a real step forward for me. Certainly it doesn’t make sense to underline "When defining" or the other first words, as they are not keywords.

    I actually prefer the Do/Don’t to the MUST/MUST NOT of the Internet RFCs, these are guidelines, not a protocol spec. Most would end up being SHOULD or SHOULD NOT, which aren’t really any clearer than Do/Don’t.

  15. Craig Andera says:

    +1 for the do/don’t pattern. The categorization is difficult to do when you emphasize the verb – how do I know "prefix" is a prescription rather than a proscription without parsing the whole sentence?

  16. Greg Wilson says:

    Our rule (the last time I worked in a place that had written guidelines) was to start each paragraph with a one-word directive:

    Do: indent code by four spaces.

    Do not: ever use tab characters to indent code.

    Do: break long expressions on commas and binary operators.

    Do not: start a line with a binary operator.

    Do: label every method parameter and class variable with a side comment.

    Do not: label method-local variables with side comments.


  17. James Bellinger says:

    The current "Do"/"Do not" way is consistent, if a bit awkward to read at times. But one gets used to it.

  18. Alan McBee says:

    I prefer the task-oriented approach to the Long List Of Dos And Don’ts approach:


    Use Tabs instead of spaces.


    Set the tab size to 4 spaces.


    (See also: Wrapping long lines)

    Wrapping long lines:

    Avoid wrapping long lines


    Do not indent wrapped lines


    or something like that…


  19. I like the do’s and don’ts – without them i worry that the point won’t come across clearly. If we don’t have them, then it will be up to the individual writer to write clearly enough, which might not allways be the case.

  20. Chetan says:

    i prefer recommendations than requirements.

    because it would have come out of things that work.

    so i prefer the defining things in the latter way.

    Thanks and regards


  21. Sam Meldrum says:

    Always and Never are better than Do and Do not and are more natural companions to Avoid and Consider.

  22. Michael Murray says:

    +1 for keeping Do/Don’t. Good reasons have already been given above, my main reason is readability: It’s an easily-scanned pattern and I never have to wonder if you’ve accidentally underlined or emphasized something with a different meaning.

  23. Eric says:

    I also prefer the current Do/Do Not format, although for some of the more annoying phrases it could be adjusted to be:

    Do: When defining a…

  24. +1 for Do/Dont pattern. It really helps drive the point and gives instant context into the type of guideline this is.

  25. Jakub Skopal says:

    I prefer using syntax which is used in RFC – stabilise the dictionary of SHOULD, MUST, etc.. You could stabilise DO, DONT, SHOULD, SHOULD NOT and use them uppercased and/or underlined.

  26. Having a clearly structured Do/Do Not/Consider will make the documentation easier to follow for readers whose native language is not English. My vote goes for Andy Smith’s suggestion that gives the best of both worlds: easy to follow and pleasant to read.

  27. Rene Schrieken says:

    A guideline is not a Law but I really think that designers/developers require ‘law’-like guidance. That is to the benefit of the project that everyone is obeying the same rules. So the Do/Don’t way of documenting is the most clear with little room for mis-interpretation.

    Mapping this kind of rules to an automatic ‘guidance’ compliance tool is easier.

  28. Ken Brubaker says:

    For my own reference, I thought I’d compile a quick list of design guidelines added by Brad Abrams, et al.

  29. Mark Levison says:

    +1 for Do/Don’t/Consider as headers – it makes it easy to scan the docs and the resulting sentences are grammatically correct.