I was recently creating a small technical documentation for an application. The document is to be used by newly hired programmers to get acquainted with the application. It is much friendlier than the Javadocs we have, and includes information that usually isn’t being documented.
When describing a function, I first bring the prototype and than the description, usage, etc. I have to choose to include argument names or omit them in the prototypes. On one hand, argument names are mostly trivial (like MyClass myClass), on the other hand they sometimes contain information of the purpose of the argument (which I will indicate when describing the function anyway).
I had the same dilemma in C++ when creating a class in two files.
Should I include argument names? Does it really work for readability?
1
Post-edit #1 – my answer works equally well for argument names or specifying the variable type, which is what I first read your question as. My answer is driven in part because I had a similar discussion recently with the use of C#’s var auto-typing keyword and a code sample we received.
In my answer”it” == argument name || variable type
Option A
In cases where it’s obvious from the type or immediate next use, then I would go ahead and exclude it in order to reduce the amount that needs to be read.
In other cases where it gives important information that’s not obvious, then you should include it.
Caveats
What’s obvious to you may or may not be obvious to the new developer reading the documentation.
If it could change then not including it could hide the fact that the documentation is now a bit out of date. Conversely, it could actually reduce how quickly the documentation gets out of date if it switches from ObviousA to ObviousB.
Option B
If you need consistency throughout your documentation, then you should always include it. As you stated, there will be cases where it isn’t obvious so if you’re picking between “always” and “never” then go with “always”.
The caveat to Option B is that you are prioritizing consistency over potential readability. It’s a perfectly valid prioritization, but you want to be aware of making that decision.
post-edit #2 – if my answer isn’t clear because I tried to be too generic, please let me know and I’ll adjust it accordingly.
2
If you ever intend to generate documentation from the header files it might be a good idea to include the names
Include them where it makes sense, and only there. It’s not an all-or-nothing choice.
2