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! ) Quote Link to comment 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. Quote Link to comment 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. Quote Link to comment 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. Quote Link to comment 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. Quote Link to comment Share on other sites More sharing options...
Recommended Posts
Join the conversation
You can post now and register later. If you have an account, sign in now to post with your account.