I’ve been using Tabnine AI with JetBrains Rider for a while now. It does a pretty good job of generating documentation comments for classes and their members – but not at all for interfaces. You can see why, because interfaces lack the implementation detail for AI to bite on.
However, it feels like the wrong way around, because I’m expecting other coders to consume my interfaces but not, directly at least, my concrete classes. It’s easy enough to generate comments for the classes and copy & paste them to the interfaces. Feels a bit like breaking the “Don’t Repeat Yourself” rule though and it at least doubles the documentation overhead for the code – not to mention comments getting stale and diverging over time.
Actually, I’m not a huge fan of documentation comments. 90% of the time they’re banal – does a comment like “The user Id” really add any understanding to a parameter called “Id” in a method called “GetUserById”?
Maybe the bit about returning a null if the user isn’t found adds something you’d otherwise have to infer (hint: return a result type) but it seems like an awful lot of noise that adds little to what the method signature tells you.
If you really need to comment your classes and their public members in order for other developers to understand them, then maybe you’ve failed to write expressive code?
When I’m working on other teams’ projects, I follow the team standards. When I’m working on my own projects I’m leaning towards documenting interfaces but not concrete classes. It does often lead to comments that don’t add much to your understanding, but it is sometimes useful & I like that the comments show up in my IDE’s intellisense. I think consistency is important, so if I document one interface I document them all.
What do other developers think? Please leave your comments below…