How Should C# Property Syntax Signatures Appear in Office SDKs?

  • Article

This post is to solicit your opinion about whether and how Microsoft should change the presentation of C# property declarations in SDK topics to take into account certain changes in the 3.0 version of C#.

Every property of a managed class has a reference topic in the product’s offline SDK and a corresponding MSDN page. Near the top of the page is the declaration signature of the class, in a monospaced font, as it would look in each of several languages. For example, the SPList.AllowRssFeeds topic has the following for Visual Basic and C#:

VB: Public ReadOnly Property AllowRssFeeds As Boolean

C#: public bool AllowRssFeeds { get; }

And for SPList.AlertTemplate , the topic has this:

VB: Public Property AlertTemplate As SPAlertTemplate 

C#: public SPAlertTemplate AlertTemplate { get; set; }

In reality, nearly all managed code at Microsoft is written in C#. The syntax examples for other languages only show, approximately, what the declaration would have looked like if the class had been written in that language. Notice that whether or not the property is read-only can be conveyed in the VB with that language's ReadOnly keyword. But C#'s little-known readonly keyword can be applied to fields, not properties. So to indicate whether or not a property is read-only, the declaration adds "{ get; set; }", for read/write properties, or just "{ get; }", for read-only properties.

This system has worked well even though the C# declarations were not literally correct syntax. Indeed, they worked well partly because they were not correct syntax. Since they were not valid declarations, there has been no danger that readers would think that the pseudo-declaration indicated anything about how the get and set accessors were implemented under the hood. Thus, the programming design principle of “information hiding” is preserved.

But with C# 3.0, a declaration such as this one:

A:

public type SomeProperty { get; set; }

is valid code and it would compile “as is.” It is equivalent to the following code. In fact, it is transformed into the following code on an early pass of the compiler.

B:

private type someField;

public type SomeProperty

{

    get { return someField; }

    set { someField = value; }

}

The C# 3.0 syntax for a read-only wrapper property simply adds a “private” access modifier to the set accessor:

C:

public type SomeOtherProperty { get; private set; }

which compiles to:

D:

private type someOtherField;

public type SomeOtherProperty

{

    get { return someField; }

}

( Note by the way, that since both A and B compile to identical IL code, no code analysis tool, such as .Net Reflector or Visual Studio’s Object Browser, can determine whether the property’s source code originated as A or B. A parallel point applies to C and D.)

The problem this creates for the property topics in our SDKs is that our presentation of read/write properties now can be mistaken for the actual implementation, especially by new developers who are coming to Microsoft managed code development after the release of C# 3.0 and are not familiar with the history of the syntax conventions on these pages.

Such a misunderstanding can, in turn, lead developers to make mistaken assumptions about the property’s get and set accessors. Our current way of presenting a read/write property declaration in our SDKs implies, since the release of C# 3.0, that the property is a simple wrapper property. This, in turn, implies several things that may be false. Among them are:

  • The set accessor does no validation on the input.
  • The set and get accessors do not directly throw (or catch) any exceptions.
  • The get accessor is simply returning a field value as distinct from calculating a value from multiple fields.

Two proposals have been made for how C# property declarations should look going forward.

Explicit Labeling Proposal:

Under this proposal, the read/write or read-only character of a property would be explicitly stated in a different font from the monospaced font of the declaration:

public type SomeProperty [read/write]

public type SomeOtherProperty [read-only]

Put the ‘Pseudo’ Back in 'Pseudo-Code' Proposal:

Under this proposal, the tradition of using pseudo-code to indicate the writeable status would be preserved, but the braces and semi-colons would be removed so that the presentation is once again not legal code.

public type SomeProperty get set

public type SomeOtherProperty get

The Office developer documentation team would like you to vote on these proposals. One way is to add a comment to this post. If you are an MVP member of the Office Content Publishing Collaboration site, you also have the option of voting on this survey page.

You may also, of course, vote to leave the property declarations just as they are, or make an alternate proposal.

One final point: Although this survey is sponsored by Office Developer Documentation, the issue is relevant to all managed code SDKs (and to the way that Visual Studio’s Object Browser presents properties). Although it will take time for all branches of the company to align on a single policy, you should vote as though you were helping to set policy for all divisions of Microsoft. It is likely that, eventually, all the affected Microsoft teams will settle on a consistent manner of presenting C# properties. In other words, do not vote against a proposal merely because it is inconsistent with the current policy of some other SDK or tool.