Let’s imagine all arguments are given proper descriptions in this phpDocumentor style. Aguments $questions and $answerSets are the same in two methods and one method simply passes them over to the other. What do you think would be the best way to handle this - repeat the same descriptions in two places or just have them in one? The passing of arguments could occur in more places so potentially the same description would need to be repeated more than two times. I’m still undecided on the best approach, what’s your opinion? Possibly, a good IDE could handle such cases automatically but I don’t think Netbeans (which I use) has such a feature.
Yes, if it is a lone programmer on his own site or application, documentation (or marketing of the code) isn’t necessary. If it is anyone selling or giving away the code for further use or extension, then it is undeniably important.
It’s not even that. You’re in a completely seperate field at that point.
If we’ve gotten to the point of looking at code comments, your marketing has already done it’s job - you’ve convinced the person/company/whatever (it does NOT have to be a ‘lone programmer’) to use your code. If they’re looking through the comments/documentation of your product, you’re trying to convince them not to give up on your code - so going into flowery overarching statements is counterproductive.
Provide a sales brochure to the guy doing the purchasing. Provide a reference manual to anyone actually using the thing.
If it is an end product with a user base, then we are talking about a different kind of target for the marketing. It would be actual end users and not programmers, so the story being told needs to be different for sure. I am thinking more along the lines of devs being the client developers of the code. You still need to market it to them too and I am not sure a reference manual is going to be totally compelling.
I agree with you, with a caveat: Describing a method in a class often doesn’t give you a firm definition of how it’s used or what the class actually does. It’s like asking the question “What does a piston do?” while trying to explain the function of an engine and while useful on its own, it doesn’t give you enough of the bigger picture to put it all together. In functional programming the function is self contained but in OOP it’s the class that does something and the methods rely (and can act differently) depending on the state of the object. This is difficult to convey by providing @param annotations and a short description. Understanding what a cell does won’t help you understand how a kidney works, for example.
That said, yes descriptions probably would help people who were looking at the code, rather than just wanting to use the library.
I completely agree with this. Look at the PHP manual, now imagine it was just a reference manual that contained the kinds of things you see in docblocks: a 1 line description, @returns, @param etc. Will this be useful? For some functions, yes, for others… not really. When I look something up on the manual the first thing I look at this the example code as it far more quickly conveys what it does than a short description.
