[SOLVED] phpdoc worth using?

[AmandaF]

I'm attempting to make the transition from being a ColdFusion programmer who writes small, procedural scripts to a PHP programmer who writes well-organized OO applications.  One of the biggest hurdles I've run into is figuring out a clean, consistent way of documenting my code.  I've tried using phpdoc syntax, and I find that I end up with comments that are significantly larger than the functions themselves.  Is this something that's supposed to happen, a flaw in the phpdoc syntax, or just me being a newbie?

 

Also, I could be wrong about this, but I'm under the impression that you're supposed to comment every class variable and method within the class.  What about ones that have self-explanatory names?  I don't really need a phpdoc block to explain that getFoo() returns the value of $foo, right?  (hypothetical example, by the way.  My variables have better names than $foo, hence the question! )

[Mchl]

Personally I use doxygen... similar concept and syntax. I just like results better.

 

And yeah... sometimes it actually leads to situations, where your comments take more space than the actual code.

 

It all depends on who else will read you documentation. If it's just for you, then you can omit documenting objects that are self explanatory. If it is also for your client, or other developers, you should probably discuss this issue with them.

[AmandaF]

I'm hoping to eventually be able to write code that I could make available as open source.  (Should I have posted this in the application forum instead?)  Taking into consideration that random developers I've never met might read the code, is there a specific format that's preferred in the PHP community?  One reason why I was interested in phpdoc was because it seemed like a standard (like how javadoc is a standard format for Java).

 

Of course, if there isn't any reason to use phpdoc, then I'll stick to short and to the point comments.

 

Thanks.

[Yesideez]

If you're going to post code for others to use then as long as everything is well documented, intended properly, decent variable names etc. then you should be fine.

 

There's nothing worse that having to edit someone else's code and have to spend ages editing it first because it's a complete mess.

[AmandaF]

OK, thanks.  Just wanted to make sure I wasn't making a faux pas by not adhering to a specific commenting style.