4

I have to write something like a styleguide for C# and I´m currently at the point where I have to figure out which comments make sense and which not. I´m working a lot with the book "Clean Code" by Robert C. Martin and some other books about C# (like O´Reillys c# 4.0) and so on ... but I cannot find a word about commenting namespaces ... ehm ... and to be honest I am not able to find any good reason for commenting a namespace. Another thing is that I want to use the XML-Documentation coming with Visual Studio and there is no default implementation for namespaces.

Do you have good reasons for me?

seveves
  • 1,282
  • 4
  • 17
  • 37
  • 4
    The question is not if you should add them. The question is, when the readers of your documentation, would they benefit from having a description of the namespace. – dtb Dec 18 '12 at 07:56
  • At the moment I would say "no, there is no benefit" ... but I need good reasons for my decision because I am rewriting an old styleguide ;) – seveves Dec 18 '12 at 08:04
  • @dtb: I'd say that is the same ;-) Iff readers benefit from the description, you should add it. (As for reasons, see my answer.) – O. R. Mapper Dec 18 '12 at 08:07
  • Developers usually think of documenting their code as a chore. But IMO the documentation should be viewed as a separate product that is shipped to the users of the code, with a thought-out user experience to increase the usability of the primary product (the code). Documenting classes and namespaces therefore isn't something that belongs in a coding style guide. – dtb Dec 18 '12 at 08:30
  • If this question is just about comments used internally and not documentation, I wouldn't bother though. – dtb Dec 18 '12 at 08:35
  • I think a comment for a namespace is only mandatory when it is an important namespace with a lot of public classes and interfaces that are need to be added in the final documentation – seveves Dec 18 '12 at 08:42
  • The problem with commenting a namespace in a source code file is that there is no single place where the comment should be placed. Either you duplicate the comment across all files belonging to the namespace or you create a dedicated file for the comment. Both options are not very attractive. For documentation targeted at the developers of the code, not the users, I would probably create a simple .txt file in the project root giving an overview of the different namespaces. – dtb Dec 18 '12 at 08:51
  • Voted to reopen because this question is a good fit for the Q&A format IMO; reasons for documenting namespaces can very well be supported by facts, references, or specific expertise, just like other questions on good commenting practice, which do not ask for a *yes* or *no*, but for reasons, such as [this](http://stackoverflow.com/questions/413985/commenting-try-catch-statements) or [this](http://stackoverflow.com/questions/2389337/how-should-comments-for-interface-and-class-methods-be-different). – O. R. Mapper Dec 18 '12 at 15:48
  • @dtb: That just holds true as long as there's no convention defined, such as the one `NamespaceDoc` class per namespace looked for by NDoc and Sandcastle. – O. R. Mapper Dec 18 '12 at 15:50

2 Answers2

3

Have a look at this MSDN page about the System.Data namespace

It provides a nice overview of what to expect of the classes in this namespace and shows the way they work together.

So there might be a good reason to add valuable documentation to a namespace.

Knowing what types to expect, to add and how to use them can be very valuable because it can be hard to gather this information elsewhere.

Emond
  • 50,210
  • 11
  • 84
  • 115
  • So would you add always a comment to a namespace or only if the namespace is worth it because of the amount of classes etc.? – seveves Dec 18 '12 at 08:14
  • 2
    It would be useful for others so they know what types to expect, add and how to use them. – Emond Dec 18 '12 at 08:55
  • The amount of classes is not that important although a namespace with many classes might need better documentation than a namespace with just a few. – Emond Dec 18 '12 at 11:48
2

There are two aspects that can (and IMHO should, where appropriate) be covered by a namespace documentation:

  • What can be found in the namespace?: Namespaces are not arbitrary groupings; the types within one namespace usually have some common theme. This categorization can be described in the namespace comments, for a single namespace identifier is seldom precise and unambiguous enough. In particular if the namespace contains a particular set of types that are meant to work together, the namespace comments are the place where the description how to use the types together should go. (Alternatively, it can inform about what types to instantiate first, or which types are the most important ones in the namespace.)
  • What may be placed in the namespace?: If the namespace is meant to be extended by third parties (that add more types to it), the comments should also describe what possible future types the namespace is suitable for, and which ones are not supposed to go in the namespace. For example, you can point out that the namespace YourCompany.Text is meant for types related to string handling, or you can point out that it is only meant for very specific plugin types for something in the YourCompany namespace. That information cannot be deduced from the namespace name alone.

What's more, if you use some documentation generator that formats the comments into a manual of some sorts (e.g. Sandcastle or NDoc), the namespace page (the one that lists all the types in the namespace) will receive the namespace doc comments as an additional information. Getting a brief overview rather than just a single namespace name and a (possibly very long) list of types can be considered crucial for a good namespace-based documentation.

O. R. Mapper
  • 20,083
  • 9
  • 69
  • 114