16

When the purpose of a method is to calculate a value and return it, I find myself documenting it as follows:

/// <summary>
/// Calculates the widget count.
/// </summary>
/// <param name="control">The control to calculate the widget count of.</param>
/// <returns>The widget count.</returns>

Here the returns tag does not provide any new information: it's just repeating what's in the summary. (The exception is methods that return bool, where it's easy to explain what the true and false return values mean.)

Am I missing something? Is there a standard way of wording XML documentation blocks to avoid repetition between the summary and returns tags?

Matthew Strawbridge
  • 19,940
  • 10
  • 72
  • 93
  • 4
    Why do you think that repetition in documentation is so bad? From a user point of view this is a good thing. I agree that it suffers from maintainability, but otherwise... – Oded Jan 26 '12 at 10:30
  • 1
    Generally one difference the `returns` serves is to provide a textual representation of the type. Such as `An integer representing the widget count.` – Grant Thomas Jan 26 '12 at 10:35
  • 1
    I'd say your example is pretty much spot on. There is generally some repetition in the tag. If you use something like GhostDoc then it will generate 75% of the above comments for you at the click of a button (if your method is named CalculateWidgetCount). – Adrian Thompson Phillips Jan 26 '12 at 10:38
  • 1
    You should definitely check out GhostDoc - I use this and it is pretty simple to use. – Bertie Jan 26 '12 at 10:51
  • 1
    FWIW I do already use GhostDoc and Atomineer. I don't have a problem with the documentation repeating information from the code (@Adrian's 75%), although the other 25% you add by hand is where the value lies. But repeating information in the same comment block just feels wrong from a [DRY](http://en.wikipedia.org/wiki/Don%27t_repeat_yourself) perspective. – Matthew Strawbridge Jan 26 '12 at 11:00

2 Answers2

11

Sometimes documentation does tend to repeat itself, especially with Properties (to an external caller they should look and feel just like simple values, so it is hard to see any point in providing both 'summary' and 'value' entries).

So I try to draw a distinction between the summary and param/returns/value etc that reduces the repetitiveness. The summary briefly describes what the method does (calculate the widget count), while the param/returns/value give detail of the inputs/outputs (and nothing else). In many cases you then see a more marked difference between the entries - reading your example, I immediately have questions about the API that the documentation doesn't answer, so I'd be hoping to see something more like one of these alternatives:

/// <summary>Recursively calculates the widget count for a given control.</summary> 
///
/// <param name="control">The root control of the subtree to process, or null.</param> 
///
/// <returns>
/// The number of widgets that are contained within 'control' and its
/// entire subtree of descendant controls (or 0 if control is null).
/// </returns>

or...

/// <summary>Calculates the widget count for a given control.</summary> 
///
/// <param name="control">The control to process. May be null.</param> 
///
/// <returns>
/// The number of widgets that are direct children of 'control', or
/// -1 if it is null/not a registered control.
/// </returns>

or even ...

/// <summary>
/// Calculates the widget 'count' for a given control using the
/// Wicker-Bartland meanest minimum average algorithm.
/// </summary>
///
/// <param name="control">
/// The Wicker-Bartland control-input-value, in the range 1.0 .. 42.6
/// </param> 
///
/// <returns>
/// The widget count, in the range -2PI .. +2PI, or Double.NaN if the
/// input control value is out of range.
/// </returns>

Unlike what @Bertie seems to be suggesting, I always try to reduce the verbosity and increase the information content - As you know what the method does, you may not need so much detail in the parameter description to describe what it is for, as it's often pretty obvious/intuitive - but you will often be able to add more detail about what values are legal or how the parameter is used, to help the reader understand how best to use it. Similarly for detail about what kind of return value I will get (e.g. whether I might get back zero, negative values, nulls, etc)

Think of this documentation as defining the code contract - the more explicitly you state the contract, the less ambiguous it becomes and the more easily another programmer will be able to work out how they can (and cannot) use your method without having to read the source code. Or identify if the behaviour of your method is as intended or a bug. Or know how much they can alter the behaviour of your method without breaking any of the existing calling code.

Of course, in some cases a method really is simple and obvious enough that you can just comment it with AtomineerUtils and move on, saving time for more important work. Often programming needs to be a balance between being practical (get the work done and the product shipped) and meeting theoretical ideals (DRY, etc).

Jason Williams
  • 56,972
  • 11
  • 108
  • 137
  • Thanks for a very full and interesting answer. I like the idea of the documentation defining the code contract, although this raises the follow-on question of how or if the style of documentation should change if you're actually using C# code contracts (which do then appear in the API docs). I think I was going wrong by expecting too much of the `summary` tag. As you've shown, the nuts-and-bolts detail is more likely to be in the other tags, and should be in enough detail that readers don't have to refer to the code even if they have access to it. – Matthew Strawbridge Jan 28 '12 at 10:43
  • @JasonWilliams: While I like the approach you describe in this answer, I see one fairly important problem with it: VS Intellisense unfortunately does not display the text in methods' `` or properties' ``. (Does it?) So if you want documentation that works well inside VS, it helps to make good use of ``. – stakx - no longer contributing Jan 12 '17 at 00:20
4

You could also try making the summary a little more verbose as to the workings of the method, without going into detail. e.g

/// <summary> 
/// Using the <paramref name="control"/> parameter, calculate the total number of widgets it contains.
/// </summary> 
/// <param name="control">The control to calculate the widget count of.</param> 
/// <returns>The total widgets contained in <paramref name="control"/>.returns>

In some cases the return value may require a little more explanation - play around with it and see what it looks like. Basically imagine someone has handed you this documentation as part of an API that YOU have to use without ever seeing the code.

Bertie
  • 733
  • 5
  • 16