0
\$\begingroup\$

I'm starting to create data models and one of the models I need should represent a mailing/billing address. While I reside in the United States, I recognize that there are different terms utilized in different parts of the world. As such, I wanted to define the properties of my model to be more generic in the sense that they can apply no matter which part of the world you're in:

/// <summary>
/// A postal code for use in company systems.
/// </summary>
public struct PostalCode
{
    /// <summary>
    /// The five digit postal code.
    /// </summary>
    public string Value { get; set; }
    /// <summary>
    /// The four digit segment code.
    /// </summary>
    public string Segment { get; set; }
}
/// <summary>
/// A universal structure for representing physical/mailing addresses.
/// </summary>
public struct Address
{
    /// <summary>
    /// The structure number and street name this address represents.
    /// </summary>
    string StreetAddress { get; set; }
    /// <summary>
    /// Data representative of a typical secondary address line.
    /// </summary>
    /// <remarks>Examples of valid data are PO boxes, room numbers, attention to descriptions, etc.
    string AdditionalDetails { get; set; }
    /// <summary>
    /// The city, town, etc. that this address resides in.
    /// </summary>
    string Municipality { get; set; }
    /// <summary>
    /// The state, province, etc. that this address resides in.
    /// </summary>
    string Domain { get; set; }
    /// <summary>
    /// The country this address resides in.
    /// </summary>
    string Country { get; set; }
    /// <summary>
    /// The division of land this address resides in. Synonymous with county, parish, borough, etc.
    /// </summary>
    string Shire { get; set; }
    /// <summary>
    /// A series of letters, digits or both, sometimes including spaces or punctuation, included in this address.
    /// </summary>
    PostalCode PostalCode { get; set; }
}

Edit: I should've initially pointed out, I do need all of the properties listed; I'm mostly focused on naming and documentation.


Is my address model to broad or "over the top"?

\$\endgroup\$
5
  • 1
    \$\begingroup\$ Keep it simple, Address, Country, City, Postal Code . these should be enough \$\endgroup\$
    – iSR5
    Aug 27, 2021 at 20:47
  • \$\begingroup\$ @iSR5 I updated my question with some details; essentially, I need all of the listed properties; my question is focused on the naming and documentation. \$\endgroup\$ Aug 27, 2021 at 20:54
  • \$\begingroup\$ Some properties comments are like explaining a hot chocolate is chocolate ! meaning, if the property name is clear enough, then there is no need to add comments on it (you could add the property name as comment). \$\endgroup\$
    – iSR5
    Aug 27, 2021 at 21:10
  • \$\begingroup\$ I had thought interfaces were off-topic. However my search indicates interfaces are on-topic. \$\endgroup\$
    – Peilonrayz
    Aug 27, 2021 at 21:25
  • \$\begingroup\$ When we had to design a similar domain model we have started our investigation at the giants: Google Maps Platform's GeoCoding Api, Microsoft Bing Maps' Location Api, Here Maps' GeoCoding Api \$\endgroup\$ Aug 30, 2021 at 6:41

1 Answer 1

1
\$\begingroup\$

Review

Explanation of details

my question is focused on the naming

The names of the variables and code elements are good, they are following the international standard which is good practice, the full class was not shared, but the code presented is ok

Yes, the structure property names are fine and clean

documentation

The comments are great, but it's a personal opinion, are you commenting the code to facilitate reading or creating the documentation in an automated way?

If it's just for visual explanation to improve the understanding of variables, it's too verbose and instead of facilitating

On the other hand, if you use some software to generate the documentation automatically, and it needs to be in this format then that's fine, it's a mandatory format to generate the PDF or HTML with the documentation, but regardless of that it would be interesting to focus on short descriptions, and there are fields that its purpose is obvious, there is no need to comment

Sorry if my explanation got a little confused

I'm using Google Translate, I hope it's understandable

Extra tip

I would like to recommend Doxygen software to create your software documentation, you just need to comment the methods / procedures / structures etc and it will generate the HTML and PDF page containing the documentation

Doxygen:
https://www.doxygen.nl/download.html

Required format when commenting:
https://www.doxygen.nl/manual/commands.html

Youtube C# Doxygen Tutorials:
https://www.youtube.com/watch?v=-V_vHZPOZfY

https://www.youtube.com/watch?v=TtRn3HsOm1s

https://www.youtube.com/watch?v=px4PTEFwioU

\$\endgroup\$

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.