Zyxist wrote: Here, even the most descriptive name can be useless: computeAmbiguityIndex(). Fine, I know that the method computes some "ambiguity index", but I don't know what this ambiguity index is, why I do or why I do not need it, where it is applied. And if developers do not want to describe the internal structure details in Programmer's Reference
Right, but what I was arguing was that the programmer's reference is a better place for that. I don't need to learn what an ambiguity index is each time I maintain that method. Only once, or very rarely would I need to revisit that documentation. The name compute ambiguity index is dead simple, if I know what an ambiguity index is, I shouldn't need anything else.
others believe it is a complete documentation. Unit tests are written for machines, it will not be completed
Wrong, they are written for humans (and one of their properties is a machine can execute them). They can document just as well if not better than a phpdoc block

Its just a matter of writing good assertion messages, which are English sentences mind you.
With a unit test you are showing what kind of output you are getting for each input. On the other hand, that is different from a docblock which shows all possible inputs & output types, but not their values or how they are related (without writing additional prose, which is basically the same thing as a unit test but not self verifying, and now you have documentation & code in the same file. We don't put business logic & code in the same file, why put documentation & code in the same file?)
I don't have a time for it. I'm a human, a single English sentence is much more expressive for me, than 200 lines of test code.
Each English sentence or 'specification' corresponds to about 2 lines of test code. Several empirical studies done by corporations such as Microsoft have shown that unit tests very rarely add to the amount of time it takes, but may subtract.
I registered the project on Ohloh, and it started claiming: "Oops! Extremely few source code comments" which was a signal: "It does not matter that you have a 0,5 MB of documentation in a text form. If you do not start using phpdoc comments, we will consider your project as poorly-designed". Maybe this is a good explaination why developers use these comments.
I don't think a comment you got on Ohloh necessarily reflects what best practice is, but I guess I would agree with you that most people haven't even heard of unit testing. I think most people would agree having tests is a good thing, but hardly do projects get criticized for not having them. So clearly you can't define best practice this way. I agree writing a docblock is a better political action to take. However not writing tests could get you impeached
