Resharper Cheat Sheet

Is there a cheat sheet available for ReSharper Keyboard Shortcuts mappings? Is there any document comparing Visual Studio built-in features to ReSharper features? ReSharper C specific. Refactoring can be a major pain if you don’t account for all of the reference changes. For instance, suppose you change the method name in a controller but forget to change it in the view. ReSharper can tell you that your code is now broken. ReSharper is a tool that runs in real time as you code and helps you catch errors as you go.

The XML documentation tags of C# are described very well in the MSDN. However, the article does not explain how the contained phrases and sentences should be written. This article tries to fill this gap by providing rules and some sample phrases.

The following is a 'cheat sheet' for the rules that apply in different situations. Dynamic 'Variables': If you want to reference the current value of a Variable in a meter or measure, and that variable is dynamically set or changed with!SetVariable, you must use DynamicVariables on the meter or measure using it.
Resharper shorcut cheat sheet Quite by chance today I stumbled across a new way to learn Resharper shortcuts. In visual studio, when editing a file, tap the ctrl key three times in quick succession.

I recommend using StyleCop because its rules enforce some of the XML documentation recommendations from this article. Also check out the Visual Studio extension GhostDoc which automates and simplifies the writing of XML documentation.

General

All XML documentation phrases should end with a period (.) and no blank:
The summary tags should only contain the most important information. For further details use an additional remarks tag. To avoid having too much documentation in your source code files, read this article which explains how to “outsource” documentation to an external file.

Classes

Each class should have a summary tag describing its responsibility. The summary often starts with “Represents …“ or “Provides …“ but other forms also exist:

Constructors

The documentation of a constructor should be in the form “Initializes a new instance of the <see cref=”TYPENAME”/> class.”</see>:

Properties

The summary of a property should start with “Gets or sets …“ if it is fully accessible, with “Gets …“ when the property is read-only, and with “Sets …“ if it is write-only:
Note: According to the very recommended book Framework Design Guidelines, write-only properties should not be used at all.
A property of type bool should start with “Gets or sets a value indicating whether …“:

Events

Each event should have a summary tag which starts with the words “Occurs when …“:
Note: Events should be named with a verb or verb phrase. Use the present and past tenses to express if the delegate is invoked before (e.g. Closing) or after (e.g. Closed) a particular event.

Methods

Like the method name itself, the text in the summary tag should start with a verb:

Method parameters

Each method parameter should have a corresponding param tag containing a description of the parameter:
If the parameter is an enum or of type bool consider starting the description with “Specifies …“ (enum) or “Specifies whether …“ (bool)
Note: According to Clean Code you should not use bool method parameters.

Method return value

If the method returns a value, you should add a returns tag which contains a description of the returned object:
If the returned value is of type bool the documentation should be in the form “true if CONDITION; otherwise, false.”:

Exceptions

The exception exception tag contains the reason why the exception occurred:
Tip: Have a look at Exceptional for ReSharper which greatly helps creating XML documentation for exceptions.

Final words

The rules in this articles are used in StyleCop and in the .NET Framework, therefore I think using them is best practice. Because it looks more clean to me, I write the opening tag, content and closing tag on a single line. Of course you can write them on multiple lines as proposed by the Visual Studio templates. For the generated XML documentation file it does not matter what style you are using.

What do you think about the described XML documentation rules? Are some rules missing in this list?

Rico Suter SOFTWARE ENGINEERING EDIT
Best PracticesXML Documentation.NETC#Cheat SheetClean CodeCoding GuidelinesDocumentation

Please enable JavaScript to view the comments powered by Disqus.

Agile “cheat” Sheet

Fellow New Yorker Agilist Dave Laribee made a present for us. A cheat sheet for Agile as a PDF:

Sure you’ve got the ReSharper 3.0 cheat sheet taped to your monitor, but what do you have that’s reminding you of values and principles? You need an Agile cheat sheet!

Luckily I’ve got one for you right here! Print it out and put it in your team room, tack it to your task board, and tape it to your monitor.

We’ve had the agilemanifesto.org homepage taped up to the wall of our team room for a while now, too, and it’s a nice reminder.

Resharper Key Bindings

The point of the post isn’t just to encourage you to follow Dave’s lead, though. You can figure that out on your own…