AmandaF Posted April 6, 2009 Share Posted April 6, 2009 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! ) Link to comment https://forums.phpfreaks.com/topic/152867-solved-phpdoc-worth-using/ Share on other sites More sharing options...
Mchl Posted April 6, 2009 Share Posted April 6, 2009 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. Link to comment https://forums.phpfreaks.com/topic/152867-solved-phpdoc-worth-using/#findComment-802803 Share on other sites More sharing options...
AmandaF Posted April 7, 2009 Author Share Posted April 7, 2009 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. Link to comment https://forums.phpfreaks.com/topic/152867-solved-phpdoc-worth-using/#findComment-803497 Share on other sites More sharing options...
Yesideez Posted April 7, 2009 Share Posted April 7, 2009 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. Link to comment https://forums.phpfreaks.com/topic/152867-solved-phpdoc-worth-using/#findComment-803543 Share on other sites More sharing options...
AmandaF Posted April 7, 2009 Author Share Posted April 7, 2009 OK, thanks. Just wanted to make sure I wasn't making a faux pas by not adhering to a specific commenting style. Link to comment https://forums.phpfreaks.com/topic/152867-solved-phpdoc-worth-using/#findComment-803578 Share on other sites More sharing options...
Recommended Posts
Archived
This topic is now archived and is closed to further replies.