Commenting code

xperience · 05-22-2008, 06:24 PM

How do you comment your code ? If it's one thing I really suck at is understanding how to correctly comment my code. I've read some things over the internet, but with still no luck.

How do you comment variables

PHP Code:


			
    /*

    * 

    * @var array

    *

        */

    public $getinfo;

    

    /*

    *

    * @var array 

    *

        */

    private $connection;

Is something like that feasible? What else would you include ? What would you change? How about a class, a function, etc ?

Village Idiot · 05-22-2008, 06:27 PM

There is no correct way to comment your code. Your comments should state what the code below it does in plain English. Don't make a novel or anything, just tell the next programmer what is going on. When making a variable, just comment on what its purpose is.

delayedinsanity · 05-22-2008, 11:12 PM

I'm crazy when it comes to commenting, and not because I'm worried about other programmers, since other programmers generally don't have their hands on my work at this point - it's for my own purposes that I comment, because no matter how into a particular method I am at the time, where I can see everything visually working together in my head, and it flows like this mornings coffee, two weeks later I can come back to something and sit there cross eyed for half an hour trying to figure out what I did if I didn't comment it.

There's three types of comment constructors (delimiters? hmm) you can use in PHP, just to rehash, there's /* -- */, // and #. Typically I use the /* version for the large descriptive comments I use at the beginning of all my library files, and for method comments (where I list the function name, the arguments it takes and what it should return, along with an area for notes as I'm in the development process) and then I'll use // for comments that are littered about elsewhere.

This is just one way of going about it. The actual correct way to do it... is... wait for it... however you want. What looks best? What's most readable? If it winds up adding more clutter and making your readability go down, then chances are you should try another way.
-m

xenon · 05-23-2008, 12:45 AM

I'm going the 'standard way', if PHPDoc has become a documenting standard. Why? Well, because I use a fully compatible IDE that recognizes the PHPDoc syntax and helps me in development (mainly), because you can generate a thorough HTML documentation without having to actually go through the code manually, and that's about it for me.

Jim · 05-23-2008, 08:17 AM

I'm fairly simple with comment, I use it allot but just to make it quicker to understand for myself if i havent touched the code in months.

This is how I commented my blog frontpage:

PHP Code:


			
<?php



////////////////////////////////////////////////////////////////////

//

// Jimnet blogging system

// By Jimmy Bokhove, Minna Media <xxx>

//

// Create a blog by template

//

////////////////////////////////////////////////////////////////////



// Get Configs

require_once('config/sql.conf.php');

require_once('config/default.conf.php');



// Get functions

require_once('geshi.php');

require_once('function/default.func.php');

require_once('function/bbcode.func.php');



// Get classes

require_once('class/template.class.php');

require_once('class/blog.class.php');



// Loop blogs

$blogContent = loop_posts(configNoPostFP());



// Create new template

$template = new template('main.tpl');



// Set template contents

$template->set('i_title', 'Jim\'s blog');

$template->set('i_description', 'Jim Bokhove\'s weblog');

$template->set('i_keywords', 'jim, jimmy, bokhove, weblog, blog');

$template->set('i_language', 'english');



// Main content (blogs)

$template->set('i_content', $blogContent);



echo $template->parse();



?>

Kalle · 05-23-2008, 10:44 AM

I use PHPDoc blocks and all my comments are the multiline comment and always having an extra * in the beginning like:

PHP Code:


			
/** This is an example */

Highway of Life · 05-23-2008, 09:09 PM

I also use the PHPDoc blocks method of commenting code. Using this for functions and class variables primarily.
Normal comments on the rest of the code as people will always need to read the code, and commenting helps in situations which could be confusing to a new programmer.

If you use an IDE such as Eclipse, ZDE or PHPEd, these comment blocks can come in handy when you are working with a project. -- You can even use a plugin in most PHP IDE's to generate code documentation based on your PHPDoc blocks.