The CLS and the Design Guidelines

David’s recent blog made it clear to me that we are not being clear on the distinction between the CLS and the Design guidelines.  Although they were developed at the same time, they are developed for very different purposes.  In david’s comments Andy is right – The 3-letter mnemonics thing is just part of the Design Guidelines, not part of the CLS.  FxCop enforces the Design Guidelines which includes things such as naming conventions for publicly exposed identifiers etc.  Another way to look at this is that the CLS is a normative (binding) part of the CLI Specification whereas the Design Guidelines are a normative (informative, non-binding) part of the spec.   


From the intro to the Design Guidelines document

Relationship to the Common Language Specification

Targeting the common language specification (CLS) is an excellent way to ensure cross language interoperation. The CLS defines a set of programmatically verifiable rules that governs the interoperation of types authored in different programming languages. Although the CLS encourages good library design, it does not enforce it. 

The CLS is a set of rules to be used by managed class library designers to guarantee that their APIs will be callable across a wide range of programming languages.

Comments (9)

  1. David Stone says:

    Oh cool. Thanks for clearing that up. So is it a one way relationship then? Adhering to the guidelines guarantees adhering to the CLI spec, but not vice versa? Or is there stuff left out of the guidelines that are in the spec?

  2. Jerry Pisk says:

    I have a question about the part of those guidelines that says that string properties should never return null. Does anybody (Brad?) know the answer to that? I mean, an empty string is something else than a missing string in many contexts.

  3. Brad Abrams says:

    The problem with returning null from a property that returns a string or array is that many of our developers expect to be able to index into the results… That is it is much nicer to be able to do:

    string firstName = n.GetFullName ()[0];

    rather than

    string temp = n.GetFullName ();

    if (temp != null) {

    string firstName = temp[0];


    It gets even harder when you consider foreach hides this slightly… Which do you like better:

    foreach (Type t in assem.GetTypes()) {



    Type[] types = assem.GetTypes();

    if (types != null) {

    foreach (Type t in types) {



  4. Brad Abrams says:

    David has a good question above as well… Yes. There is a Design Guideline rule that says you should adhear to the CLS, so in a way the Design Guidelines is a super set but only by reference… we don’t repeat all the CLS rules.

    The best way to adhear to the CLS is to use the compiler support (today only in C#, but commig in the other MS languages soon)… You just put the [assembly:CLSComplaint(true)] in your project and the compiler helps you ahear.

  5. Jerry Pisk says:

    Brad, the same people also expect that the array will have at least one element, so not only you should never return a null object instead of an array but obviously you should also populate it with the maximum number of elements developers might expect to get back (your first example will fail if you return an empty array and you should return at least four empty strings in it, first, last, middle initial and title). I’m sorry, that rule only encourages developers not to check return value which is a very bad practice.

  6. Ken Brubaker says:

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

Skip to main content