rlelek Posted March 29, 2009 Share Posted March 29, 2009 Hello Everyone! I have been searching around on google, but couldn't find any coding documentation best practices. I was just curious what guidelines everyone has for providing documentation. I comment my code often, but now that a new development team will be getting involved, we would like a nice, universal commenting structure. Of course, in-line comments will be unique, but... What are some common/important things you would suggest to include in the document's header/first lines of code? Thanks! Link to comment https://forums.phpfreaks.com/topic/151586-documentation-guidelines/ Share on other sites More sharing options...
Floydian Posted March 29, 2009 Share Posted March 29, 2009 The Zend Framework has published a pretty robust set of coding conventions. I'm sure you'll find some good stuff there. http://framework.zend.com/manual/en/coding-standard.coding-style.html#coding-standards.inline-documentation Hope that helps... Link to comment https://forums.phpfreaks.com/topic/151586-documentation-guidelines/#findComment-796128 Share on other sites More sharing options...
redarrow Posted March 29, 2009 Share Posted March 29, 2009 do you mean some think like this. the information is written to the file while the programmer is working on that page. <?php ################################################# # Date Created: # # Programmers Name: # # Page Refrence: # ################################################# ################################################# # Date Created: # # Programmers Name: # # Page Refrence: # ################################################# ?> Link to comment https://forums.phpfreaks.com/topic/151586-documentation-guidelines/#findComment-796129 Share on other sites More sharing options...
rlelek Posted March 29, 2009 Author Share Posted March 29, 2009 The Zend Framework has published a pretty robust set of coding conventions. I'm sure you'll find some good stuff there. http://framework.zend.com/manual/en/coding-standard.coding-style.html#coding-standards.inline-documentation Hope that helps... Thank you *very* much! This is a gold mine. I tried to look around PHP.net for something like this, but didn't even think to look at Zend. @redarrow, Thanks, that's what I am after. just some general information before diving into the code for the first time. Besides the specified Zend guidelines (which are very good)... any other specific things you would like to have had before beginning to code for a project? Here are the Zend guidelines.... B.4.7.2. Files Every file that contains PHP code must have a docblock at the top of the file that contains these phpDocumentor tags at a minimum: /** * Short description for file * * Long description for file (if any)... * * LICENSE: Some license information * * @copyright 2008 Zend Technologies * @license http://framework.zend.com/license BSD License * @version $Id:$ * @link http://framework.zend.com/package/PackageName * @since File available since Release 1.5.0 */ B.4.7.3. Classes Every class must have a docblock that contains these phpDocumentor tags at a minimum: /** * Short description for class * * Long description for class (if any)... * * @copyright 2008 Zend Technologies * @license http://framework.zend.com/license BSD License * @version Release: @package_version@ * @link http://framework.zend.com/package/PackageName * @since Class available since Release 1.5.0 * @deprecated Class deprecated in Release 2.0.0 */ Link to comment https://forums.phpfreaks.com/topic/151586-documentation-guidelines/#findComment-796133 Share on other sites More sharing options...
redarrow Posted March 29, 2009 Share Posted March 29, 2009 if it a huge programmers job where thousands are contributing work. then create a database and user logs in to download there page's there working on, then print there name at the top off the page and other info. once they have finished ask them to log in upload the project, keep doing that keep re written on the top of the page who done what. there nothing in documenting pages be honest. page name. page reference. programmers name programmers email copy wright. build refrence. bugs. date downloaded. date uploaded. start date end date. hours worked on. hours needed. code added , (example php,mysql,css) cost if applicable. as you can see, you can make it all up, it all free fun. Dont over do it in thinking to hard your never get the job/project done. Link to comment https://forums.phpfreaks.com/topic/151586-documentation-guidelines/#findComment-796137 Share on other sites More sharing options...
Recommended Posts
Archived
This topic is now archived and is closed to further replies.