Timeline for Documenting Dependency Injection Parameters
Current License: CC BY-SA 4.0
13 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Aug 26, 2019 at 16:53 | comment | added | mark.monteiro | Thanks @KolA, for now I have been using the [SuppressMessage] attribute, which doesn't bother me that much in terms of keeping the code clean. I am not going to make the constructors internal because I will be using them for unit tests in a separate assembly. This question is more about deciding whether I should suppress the messages at all, rather than how to suppress them | |
| Aug 26, 2019 at 15:52 | comment | added | KolA | also suppressions can be moved to separate source file to keep source code clean but it is far from ideal. The only alternative I can think of is to write custom attribute and Code Analysis rule (via Roslyn) but this is probably overkill. | |
| Aug 26, 2019 at 15:50 | comment | added | KolA | @mark.monteiro looks like the only way to avoid explicit suppression is to configure StyleCop to allow constructors with internal (or protected internal) access modifier to be undocumented; and make all "injection" constructors internal. I don't know whether StyleCop or your DI container allows this. | |
| Aug 26, 2019 at 15:47 | history | edited | Robert Harvey | CC BY-SA 4.0 | deleted 13 characters in body |
| Aug 26, 2019 at 15:17 | comment | added | mark.monteiro | @KolA I have added an edit to my question with additional context. I am using StyleCop to enforce rules about documenting function parameters. | |
| Aug 26, 2019 at 15:17 | history | edited | mark.monteiro | CC BY-SA 4.0 | Additional context on integration with StyleCop |
| Aug 26, 2019 at 12:47 | comment | added | KolA | are you asking about XML comments? Do you enforce them somehow? (they are easy to enforce on all public/protected members in VS C# project settings: Properties -> Build -> Output -> XML Documentation File). There's a good chance that your constructor or its class can be marked as internal i.e. XML comment is optional, and if comment doesn't provide any information beyond trivial then you don't have to write it. | |
| Aug 24, 2019 at 8:52 | answer | added | Anders | timeline score: 0 | |
| Aug 24, 2019 at 6:42 | answer | added | candied_orange | timeline score: 4 | |
| Aug 23, 2019 at 22:24 | comment | added | Filip Milovanović | These parameters are really no different than any other kind of parameters. Also, when you are documenting a parameter, you are not necessarily describing the concrete service, but the role it plays within the confines of the class, for the benefit of the developer who is trying to understand how the class fits in a larger context. So if you have something to say that's relevant in that sense, then document them, if not, then don't (in particular, comments that just restate the exact same information contained in the code itself are useless clutter). | |
| Aug 23, 2019 at 20:33 | comment | added | Doc Brown | Is the type name of those injected parameters "self-describing enough" for your taste? | |
| Aug 23, 2019 at 20:15 | review | First posts | |||
| Aug 24, 2019 at 5:24 | |||||
| Aug 23, 2019 at 20:11 | history | asked | mark.monteiro | CC BY-SA 4.0 |