TalkPHP - Commenting code

TalkPHP (http://www.talkphp.com/forums.php)

- General (http://www.talkphp.com/general/)

- - Commenting code (http://www.talkphp.com/general/2839-commenting-code.html)

xperience

05-22-2008 06:24 PM

Commenting code

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.

caiyanfang

03-30-2013 07:52 AM

'Lindsay's been telling everyone that she moved to Ny because she was sick of ralph lauren outlet online la. But that's simply not true, she so want to move back gulf of mexico, but she won't.

'In the past, Lindsay has were able to rope in anyone to co-sign out on leases because her credit score means she aren't going to get approved in her name alone. ralph lauren polo outlet shop

'However, she couldn't verify anyone polo ralph lauren outlet online willing accomplish this now as brand-new areas such as burned so any one of her friends and are associates. '

caiyanfang

03-30-2013 07:58 AM

Jack Hard

04-01-2013 06:57 AM

I'm also crazy when it comes to comments not because I worry about other programmers, and other programmers usually have jobs my hands right now - this is for my own needs, I commented because the issue in this way I am particularly when they can visually see all work together in my head and pour the coffee in the morning, after two weeks, you can return to something and cross your eyes to stay there for half an hours trying to figure out if I do not comment.

There are three types of constructors (separators comment right?) Can be used in PHP, restatement, no / * - * / and / / #. Usually, I use version / * descriptive comment for large I use at the beginning of all my library files, and comments on the method (if I enter the function name, the arguments they take and he must return with areas of note, while I'm in D), then I'll use / / for comments, which were on the other side.

It's just a way to make room veschi.Realny doing things ... it ... wait for it ... However you want. What looks better? What could be easier to read? If you find yourself adding more confusion and make readers down, chances are, try another way.

All times are GMT. The time now is 06:19 AM.