Should documentation be added for constructor parameters that are passed via dependency injection? In my current project I have decided to omit documentation to describe each of these parameters and my reasoning for this is as follows:
-
These constructors are not meant to be called by a developer (outside of unit testing, but I will only be using integration testing in this project) so why bother documenting the parameters passed to them? The parameters are passed by a DI framework, which isn’t going to read the documentation when constructing these classes.
-
Many of the services being injected are singletons. By adding parameter documentation for every constructor to which they are injecting, I’m adding a bunch of duplicate documentation all over the project. Now, if the semantics of how that service is used changes later, I will have to update the comments in every constructor. It seems like a better solution for the developer to just go look at the class documentation for the service.
Is this reasoning sound? Are there any reasons you would disagree with my rationale for excluding these comments? Are there potential benefits of including these comments that I have overlooked?
To add some further context to this question, these are XML comments in C# that will eventually also be used to generate documentation for the project. I am in the process of integrating StyleCop into the project which has a rule to make sure that all function arguments are documented. So this issue arose because I am being forced to choose between documenting these parameters or suppressing the warning messages for each constructor using injection. I do not want to disable the rule globally because I do want to ensure that parameters for regular methods and constructors are documented.
7
If you can’t refactor without changing your comments your comments are too coupled to your code.
Comments should never describe how the code works. Comments should describe why the code is does what it does. Or at least, what it was supposed to do. Show your intent not your method of achieving your intent.
As Doc Brown points out a good name makes leaving off comments perfectly acceptable. Comments should never be redundant duplications of what the code tells you.
Now all that said, if you go completely without comments your code had damn well be extremely readable with no surprises.
Read your code while giving thought to how it will look to the next programmer. Give them what they need and no more.
There is nothing special about parameters, DI or otherwise, that requires comments in any special way.
So please, spare us comments that add no new information and are needlessly coupled to the code like this:
//reads a file
public void read(File file){
...
}
Comments should add something new
//Parse all numbers and load them into a collection
public void read(File file){
...
}
Which is better but should lead to this:
//Loads into a collection
public void parseNumbers(File file){
...
}
Or even this:
public List<Integer> parseInts(File file){
...
}
And now you don’t need any comments at all. You already know what it does.
But you don’t have to take my word for it. I’ve asked about this before.
1
You should never comment how, only why. The code is the how-comment in it self (If its not refactors are in place).
Dependencies are 99% of the time irrelevant to the why-question.