Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
1  
I would venture that argument names should always contain information of the purpose of the argument. If they are mostly trivial, I think your coding standards need review. –  mattnz Mar 13 '13 at 20:58
add comment

3 Answers

up vote 1 down vote accepted

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.

share|improve this answer
    
Thanks for your answer. btw It never occurred to me how similar this is to using var in C# ))) –  superM Mar 13 '13 at 13:35
1  
@superM - you're welcome. It helps that I misread your question at first. :-) When I went back to make sure I covered all of your concerns, I realized the duality. –  GlenH7 Mar 13 '13 at 13:56
add comment

If you ever intend to generate documentation from the header files it might be a good idea to include the names

share|improve this answer
add comment

Include them where it makes sense, and only there. It's not an all-or-nothing choice.

share|improve this answer
2  
I'm more for consistency, so this approach looks a little like having different coding styles in the same project –  superM Mar 13 '13 at 10:18
1  
This is a single consistent style. Sure, you use X in one place and Y in another, but that can still be a single style. Cf. when you use lowercase for method names and uppercase for type names, are you using a single consistent style for your identifiers? Consistency just means doing the same thing in the same situation. –  MSalters Mar 13 '13 at 10:36
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.