Documentation Guidelines?

[rlelek]

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!

[Floydian]

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...

[redarrow]

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:                      #
#################################################

?>

[rlelek]

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
*/

 

 

[redarrow]

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.