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?

  • 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. – David Arno Jun 7 '18 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. – Konrad Jun 7 '18 at 8:51
  • 2
    @Konrad then maybe it should be called IsoSymbol? – Kevin Van Dyck Jun 7 '18 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. – David Arno Jun 7 '18 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. – Jesse C. Slicer Jun 7 '18 at 14:10
-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.

  • 2
    The "Gets or Sets" language looks unnecessary and verbose. The comment adds nothing above what we can already tell from the code. – Graham Jan 14 '19 at 16:25
  • 1
    It is true the former answer wasn't the correct answer not even close, excuse me. – Enver Daniel Francisco Báez Jan 14 '19 at 18:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.