3

When writing a class which has ("satisfies") 1 or more interfaces, should I note somehow (e.g. in an XML comment, or with an attribute) that a particular method was added for one of the interfaces?

For example, the IComparable interface requires an int CompareTo(Object) method.

I know I don't need to do anything other than implement the appropriate methods, but for maintainability and ease of understanding are there any "best practices" for letting others know why the method exists?

0
0

Yes. Your inclination is sound. You should leave a comment in the method's source code and/or larger documentation.

// Implements IComparable interface

in the method source should do the trick, allowing those who will be reading the code closely (you later on, or someone else maintaining, modifying, or adapting it) to easily and rapidly acertain why the method exists.

If the method is part of a promoted API, it can also be mentioned in the API docs (the form of which will vary based on what documentation system you're using).

Even if you're not fully committed to literate programming, in which an explanation of the code is considered co-equal to the code itself, it is an excellent practice to use comments in the program source and notes in the API documentation to explain how the program works, why it is defined and implemented as it is, and how to use it.

3
  • What if the interface drops the method from its signature later on? Then, your comment is incorrect and confusing (as all comments become eventually) and no compiler check will catch it.
    – Graham
    Oct 3 '14 at 13:42
  • @Graham but your comment will at least explain why the method was added in the first place, allowing a later editor to tell what the original intent was and make a better judgement as to whether or not it can be removed.
    – Dave
    Oct 3 '14 at 14:09
  • @Graham Yes, if the interface changes, the docs will be out of date. Which is true of all API definitions, program contracts, etc. That changes may supersede or obviate documentation is not a good reason to not document. Oct 3 '14 at 15:49
3

There should be no need to treat the method any differently than any other. In this example, a method named CompareTo() would be obvious to anyone with significant .NET experience as being the implementation of IComparable<T>. The idiot who comments it out or deletes it will be told by the compiler that the class no longer implements IComparable<T>.CompareTo(), and at that point should understand they messed up and put it back. The total bozo who, on receiving this error, thinks the best solution is to remove the IComparable<T> interface from the class definition (without one hell of a good reason, like he's traced every usage of the class across your codebase and is 100% positive the class is never part of any sort operation) probably doesn't need to be working for your company.

If you wanted to be nice, //Implementation of IComparable<T> placed somewhere near the function declaration (just above it, or just inside the function body) should make it clear enough even to the boneheads mentioned above.

If you wanted to be really nice, you can xml-doc the class/method, and in the <remarks> tag, affirm that this method is the implementation of IComparable<T> for the class. This will not only show up in source, but also in any SandCastle documentation you create. It might show up in IntelliSense, but I doubt it; remarks can be pretty big. If it absolutely positively has to be known via IntelliSense that the method is the implementation of the interafce, mention it in the <description> tag.

1
  • Thanks. The IComparable example was just to identify exactly what I was talking about, in reality my concern was for more obscure interfaces that only exist within our project and whose methods might not be obvious
    – Dave
    Oct 3 '14 at 14:05
-1

Put the methods that satisfy the interface into a #region.

#region IMyInterface Members

// methods that satisfy interface

#endregion

Visual Studio even has a shortcut for creating this region and method prototypes for each method in the interface, available by right-clicking on the "inherits from" declaration in the class definition, and selecting "Implement Interface."

In other words, Microsoft sees this as a best practice.

Naturally, nothing prevents you from putting in an XML comment that says "This method satisfies the Iinterface1 and Iinterface2 interfaces."

10
  • 7
    Bleh, regions are vile - also, a single method may satisfy multiple interfaces, the auto-generate methods won't actually add a method for an interface if it was already covered by another.
    – Telastyn
    Oct 2 '14 at 16:59
  • 2
    @dave - personally, I wouldn't mark the method as special in any way, and work to keep my classes (and interfaces) small enough that it's fairly obvious what is going on. That said, I'm not confident enough in that approach to recommend it as best practice to a wide audience.
    – Telastyn
    Oct 2 '14 at 17:12
  • 3
    quite the opposite: StyleCop has a specific rule about avoiding regions
    – Dan Lyons
    Oct 2 '14 at 17:56
  • 1
    The only situation in which I use a region is to effectively mark code "Do Not Touch". Stuff like unsafe code, P/Invoke calls, and certain interface implementations that add a lot of LOC (for instance, IConvertible) are easily collapsed and ignored by junior coders (and by me for that matter, as long as the tests pass).
    – KeithS
    Oct 2 '14 at 22:57
  • 1
    Took a look at some blog posts about #regions. I genuinely don't understand the hate. #regions are just another organizational tool; if your beef is with code folding, then why don't we just dispense with code folding altogether? Oct 3 '14 at 14:04

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.