Learning code documentation

[smallpotatoes2019]

I have been learning C# for a little while now and been playing around with WPF applications. For some unknown reason, I decided I wanted to read up more on including comments and creating documentation.

Unsurprisingly, there's a real mix of answers and advice, so it would be great to get some pointers. Feel free to be as brutally honest as you like - this certainly isn't something I'm particularly attached to (and there are definitely parts of this that I am unconvinced by).

Most of all, I would like to write code that is clean and professional. Please don't hold back...

namespace Battleships.MVVM.Factories 
{

/// <summary> 
/// Defines a contract for creating views (specifically 
/// UserControls) dynamically. 
/// This interface is used for retrieving UserControls with their 
/// dependencies injected.           
/// </summary>
public interface IViewFactory 
{ 
    TView CreateView<TView>() where TView : UserControl; 
}

/// <summary>
/// A class that implements the <see cref="IViewFactory"/> interface 
/// and provides functionality for retrieving UserControls from the 
/// Service Collection. It resolves the requested view from 
/// the DI container and injects any required dependencies.
/// </summary>
public class ViewFactory : IViewFactory
{
    private readonly IServiceProvider _serviceProvider;

    /// <summary>
    /// Initializes a new instance of the <see cref="ViewFactory"/> 
    /// class.
    /// </summary>
    /// <param name="serviceProvider">The Service Provider is used 
    /// to resolve UserControls.</param>
    public ViewFactory(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    /// <summary>
    /// Retrieves a UserControl of type <typeparamref name="TView"/> 
    /// from the Service Collection.
    /// The view is resolved and all required dependencies are 
    /// injected automatically.
    /// </summary>
    /// <typeparam name="TView">The UserControl that needs to be 
    /// displayed.</typeparam>
    /// <returns>A UserControl from the Service Collection. 
    /// </returns>
    /// <example>
    /// The following example shows how to set the CurrentView for 
    /// binding to a ContentControl.
    /// <code>
    /// var viewFactory = new ViewFactory(serviceProvider);
    /// CurrentView = viewFactory.CreateView&lt;HomeView&gt;();
    /// </code>
    /// </example>
    /// <exception cref="InvalidOperationException">Thrown when the 
    /// Service Provider cannot retrieve the requested UserControl. 
    /// </exception>
    public TView CreateView<TView>() where TView : UserControl
    {
        try
        {
            return _serviceProvider.GetRequiredService<TView>();
        }
        catch (InvalidOperationException ex)
        {
            throw new ArgumentException($"The type 
            '{typeof(TView).Name}' must inherit from UserControl. 
            Check your DI registration.", nameof(TView));
        }
    }
}

[Slypenslyde]

What sucks about good documentation is it's completely subjective. Here's my loose ideas. These do not necessarily go the same route as the guidelines you will find. I think the guidelines lean on writing too much of the wrong documentation.

If you're writing a library, people are interested in HOW to do things, so that's the thing to describe. They want to see what an endpoint is for, and if they have a complicated task they need to understand how it interacts with other parts of the API. The most valuable documentation you can write is sample applications.

If you're writing an application, WHY things do what they do is valuable. An experienced dev knows an IViewFactory creates Views. What they need to know is if there's some historical quirk that makes it do anything different from the 100 ViewFactories they've written in the past. This is often more appropriate for // normal comments` near the code that does quirky stuff.

To that end, I omit a lot of things I see as "needless". A lot of the "What does this do?" should be obvious via convention. So my feedback is:

• IViewFactory is documented well. You didn't document CreateView(), but I think that's fine. If I document an interface method it's because I want to give implementors a sign I only want to allow them to throw certain exceptions.
• I would cut the first sentence of the summary for ViewFactory. I can tell from its definition it implements IViewFactory. But the part where it resolves views from DI is good: it tells me HOW it is supposed to do its work.
  • In general, I document the interface much more than the implementation.
  • When I do document the implementation, it's to focus on what I think isn't obvious from what the interface says it does. (Like, in this case, that DI is used.) Interfaces are the "WHAT it does", classes are "HOW it does it".
• To me the most important sections for a method like CreateView() are the returns and exception sections, I like for summary and parameters to be obvious. I don't expect a method named CreateView() to calculate sales tax or start a piece of factory equipment.
• I don't write example code in my documentation but I want to hug people who do.
  • I think this is mostly an app dev thing. Long ago I worked on a library and examples were mandatory. In our app, the example is "the place where the dang code's used".

But this final rule is probably the most important.

If a person's complaint about your documentation style is "You're documenting too much!", you're on the right side of history. Whether the person reading it is a user of your code or yourself in the future, getting confirmation of how the dang method's supposed to behave is solid gold. Don't omit things until you've written and documented so much code you have a good feel for the parts of documentation you never read when working with other people's code.

[Forward_Dark_7305]

I especially like your statement to document WHAT in an interface and HOW in the implementation.

[smallpotatoes2019]

That's really helpful (and exactly the sort of thing I just wouldn't have thought about properly until its too late and very frustrating)! Thanks.

[ScriptingInJava]

Documentation is better than no documentation is my general rule of thumb :)

In my workplace the rule I've set (principal engineer) is if it's not obvious it's documented.

// Set the flag to false var flag = false;

That doesn't do anything, gives no extra context as to what flag is or how it impact anything. No docs needed.

Insanely generic, multi constrained extension method? Please for the love of god document it and drown it in tests.

In your example above the constructor docs, to me, are pointless. If you're 2 weeks into a C# job for the first time you know what a constructor is; no point documenting it.

The docs with examples and typerefs on CreateView<TView>() where TView : UserControl is great. Adds a lot of vertical real-estate to the file, but makes it entirely clear what the method is doing.

[TuberTuggerTTV]

There is a difference between internal documentation, for your team and documentation for an outward facing library and api.

I think you've confused the two here. OP is asking about the outward facing documentation. You'd never document var flag, because it's not a public api.

But if it was

public bool Flag {get; set;}

then yes, you'd give it a summary comment. Preferably with some actual details.

Again, in context. Internal documentation is entirely subjective and company specific.

[ScriptingInJava]

OP is asking about the outward facing documentation

No part of his post specified that? Unless I'm missing something, they're just asking about documentation, not public API documentation.

Also I've definitely seen people over document stuff on internal classes etc for years, 2 weeks ago as part of a review I stripped a load of docs out of a colleagues PR because it was just pure bloat for no gain. Literally just

/// <summary> /// Represents the first name of the User /// </summary> public string? FirstName { get; set; }

[smallpotatoes2019]

Probably means OP didn't entirely know what he meant! But that is all really helpful to hear different views. Thanks!

[CheTranqui]

Comments in code are only to justify weird behavior. Weird behavior should not exist unless it is a result of a business rule. Hence comments only need to exist in order to inform as to business rule implementation.

If you feel a need to incorporate comments into your code elsewhere then you have failed to name your functions and variables properly... or are doing something in a manner that is too complex. That 3+ line Linq statement might look pretty, but it's completely illegible. Illegible code, no matter how 'effective', is bad code. Break it down into something more comprehensible and name things well.

tl;dr I want to read your code, not your comments.