Joe Stump [2008-11-12 21:24 UTC] I agree with everything, but the omission of @return. PHP still doesn't have any way to imply anything other than void. PHPDocumentor could indicate that *something* is returned, but not what that thing is.
I'd recommend this remain explicit.
Till Klampaeckel [2008-11-12 21:35 UTC] I'm fine with all your spacing issues, even though I can't really relate to them being such a problem. However I'm for keeping @return and also the parameter name in @param.
It's just easier to read and connect when I look at code which I haven't written myself.
Also, I feel like one important issue is almost always overseen when people voice their opinion on the coding standards and how obnoxious it is to follow them.
We should keep in mind that one is most likely to not write documentation for yourself - but for other people who use the code.
I found that our CS while maybe hard to get used to, is really helpful when it comes to looking at someone else' code. It's just easy to get into it. And it's even easier for myself to get back into my own code which I haven't looked at in six months.
Greg Sherwood [2008-11-12 21:43 UTC] I think having the param name in @param is important. While it may be your intention to ensure they are always in the correct order, I've been caught by phpcs a few times where I have changed the order of params after writing the docs and forget to reorder the tags.
Having the param name makes it clear what param the documentation was written for, which makes it far easier for the next developer who comes along to read the code docs or generated docs. Automated tools are never going to know which param you were talking about, so it is likely that some docs will be generated with documentation assigned to the wrong param, which is IMO just as bad as having no docs at all.
Brett Bieber [2008-11-12 21:59 UTC] I think @return should be kept, and the @param var names ensure you are documenting the correct parameter.
As a side note, the constitution states that Coding Standards are the purview of the PEAR Group. Keep the discussion going, but keep in mind you're asking the PEAR Group to make changes.
Arnaud Limbourg [2008-11-12 22:07 UTC] The changes make sense. Considering @return, it seems redundant to have "@return void" if the method does not return anything but on the other hand when reading the code it is very clear from the beginning that the method will not return anything.
I'm unsure about the @return suggestion.
Jorrit Schippers [2008-11-12 22:19 UTC] I think the original issue was that comment related CS were littering the output of phpcs with errors such that the code related CS issues became hard to spot. I think this proposal is a bad solution to this problem. PHP_CodeSniffer could be adapted such that one can distinguish between these two classes of problems.
I fear that with this proposal accepted, different styles of commenting start to appear within one file, and as a result it will look more and more sloppy. If one understands the comment style guide before one starts coding, there is no extra effort needed to remain CS compliant. I suggest the CS guide to be made more explicit instead of less explicit, such that the CS is properly documented instead of implicitly documented in one example.
I understand that I should have brought this vision in the PEAR-DEV list discussion preceding this PEPr, but I forgot to do this.
I think the param name in @param should be kept. This is far more common practice in PHPDoc than without, and is as such more compatible with editors like Eclipse/PDT.
Christian Weiske [2009-06-25 08:06 UTC] Is this proposal dead, or are you going to finish it?
|
