0

I have 2 models, DTOs and database models (entities) that map to the database.

I usually put XML comments above the properties to describe what are they for.

class MyEntity
{
    /// <summary>
    /// Some summary
    /// </summary>
    public string SomeThing { get; set; }
}

Should I put these comments in my DTOs or entities?

Improve this question
8
  • 2
    "I usually put XML comments above the properties to describe what are they for". I wish you wouldn't. If the name of the property doesn't describe what it's for, fix the name, rather than polluting the code with noisy comments. Commented Jun 7, 2018 at 8:41
  • @DavidArno What about examples of values that it can contain, for example, I have my property named Symbol and user doesn't know what kind of symbol, maybe it should be a symbol in ISO format or something. Commented Jun 7, 2018 at 8:51
  • 2
    @Konrad then maybe it should be called IsoSymbol? Commented Jun 7, 2018 at 9:18
  • 1
    As @KevinVanDyck says, don't have a property called Symbol; have a name that describes what sort of symbol and or what it's used for. Commented Jun 7, 2018 at 10:39
  • 1
    Yes, please put them on the DTOs - those should then be parsed by a documentation generator (such as Swagger/Swashbuckle) for your API consumers to reference. Include the seealso and example tags for the same reason - show the usage. On entities, eh, not a lot of valid in my opinion unless you're pulling data dictionary metadata from somewhere and decorating them with that on (re)generation. Commented Jun 7, 2018 at 14:10

1 Answer 1

Reset to default
-3

If the DTO and the entity are quit similar you shouldn't duplicate the documentation but you can reference the entity from the DTO and its properties.

With the inheritdoc tag:

/// <summary>
/// Some summary
/// </summary>
class MyEntity
{
    /// <summary>
    /// Some summary
    /// </summary>
    public string SomeThing { get; set; }

    /// <summary>
    /// Some summary
    /// </summary>
    public int SomeThingElse { get; set; }
}

/// <summary>
/// Some summary <see cref="MyEntity"/>
/// </summary>
class MyDTO
{
    /// <inheritdoc cref="MyEntity.SomeThing"/>
    public string SomeThing { get; set; }
}

The feature Add a way to inherit documentation #313 i'm using .net framework version 4.6.1.

Isn't well documented on dotnet just for a few petition in the former link, but with some extensions or nuget pacakge you can used too if your version dotnet doesn't supported.

Improve this answer
2
  • 2
    The "Gets or Sets" language looks unnecessary and verbose. The comment adds nothing above what we can already tell from the code. Commented Jan 14, 2019 at 16:25
  • 1
    It is true the former answer wasn't the correct answer not even close, excuse me. Commented Jan 14, 2019 at 18:48

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.