Question

Is there a way to add comments to document a Dictionary or ConcurrentDictionary to know what the key / values mean?

For example:

Dictionary<guid, string> _users;

This example has a dictionary of users. The guid is the UserId and the string is the username, but it’s hard to tell other than just “knowing”.

Is there a way to add docs so that when you add items, intellisense tells the developer a note about the key & value?

I know I can add a <summary> comment above it and it puts that note in the object itself, but was looking for when adding, removing, etc.

Answer 1

Recently in GOOS book I found interesting idea of packaging common types (such as collections) in own classes:

Try to use the language of the problem you are working on, rather than the language of .Net constructs. It
reduces conceptual gap between domain and code. Also try to limit
passing around types with generics. This is a form of
duplication. It’s a hint that there is domain concept that should be
extracted to type.

Frankly speaking I’m not so extremal in packaging common generic collections, but even giving a type own name makes it match easier to read and understand:

public class UserNameDictionary : Dictionary<int, string>
{
}

Very simple. And now what is better to read:

Dictionary<int, string> users = new Dictionary<int, string>();
UserNameDictionary users = new UserNameDictionary();

Also you can quickly add comment to your class:

/// <summary>
/// Represents a dictionary of user names accessed by ids.
/// </summary>

This will not add comments to methods like Add(int, string), but when other people will use this class, they will think in context of UserNameDictionary, not in abstract Dictionary<int, string> context.

If you want to make your class more handy, you can hide base class methods:

public new void Add(int userId, string userName)
{
    base.Add(userId, userName);
}

For more complex use cases I’d go with custom class which delegates work to internal dictionary.