to document or not to document

[eluser]codeamatic[/eluser]
That is the question. Considering the nature of CI and its MVC like behavior. Is it necessary to document public methods (in a controller) associated with the URI?

Currently this is what I do?

Code:

//-----------------------

function aboutus()
{
    //....
}

//-----------------------

function contactus()
{
    //....
}

//-----------------------

/**
* Phpdoc for private methods
*/
function _filter_records()
{
    //....
}

I document all private methods throughout the project but wasn't sure if it was necessary to document these public methods.

[eluser]Rob Steele[/eluser]
Sup,
Personally, I've found it that I am always happy when I document everything. This is especially true if you have some way of accessing your db or tables in which might not be totally clear in the future. Regardless of the function it's good style to me. That's my 2 cents.
-Rob

[eluser]TheFuzzy0ne[/eluser]
Always document each function/method/class regardless of it's access level. It helps any other developers who may be involved in the project in the future, and also helps you 6 months down the line when you need to go back and fix/change things. Documenting every function religiously demonstrates consistency, which is a good trait for any developer.

[eluser]codeamatic[/eluser]
thanks for the input...I guess I will be documenting them after all...

[eluser]JayTee[/eluser]
While I agree that it's important to document your code, it's possible to go overboard.

Here's an example of what I think is bad documentation:

Code:

/*
* Get user information and display it
*/
function get_user()
{
  //get the user id from the url
  $user_id = $this->uri->segment(3);

  //get the user details from the database
  $this->load->model('user');
  $user_data = $this->user->get_details($user_id);

  //load the data into the view
  $this->load->view('user_page',$user_data);
}

Why do I think this is bad? Because the code documents itself. A brand new developer (you have to at least make a small assumption that they know CI) can read this code without any comments and it will make sense. Unfortunately, I see these types of line comments ALL THE TIME - those things just add to the clutter.

So, when *is* it a good time to document your code? Here are my rules of thumb and why:

1. Document all function/method declarations
My IDE has a cool feature that searches my project for class methods/functions and the types of inputs they need. This applies to both the existing PHP functionality, the CI framework (as long as the function is documented) and any classes/functions/methods I write. If I use the standard [url="http://manual.phpdoc.org/"]PHP-Doc[/url] format, all of my function calls give me handy code-completion within the IDE. This speeds up typing when I write my code - so I spend more time programming than typing

2. Don't use a comment to explain how it works - that's what the code explains by itself. Use a comment to explain [b]why it works.[/b]
Here's a snippet of code from a certain CI Library:

Code:

//(before)

if (preg_match("/\{".$val."\}(.*?)\{\/".$val."\}/si", $this->template, $match))
{
  $this->temp[$val] = $match['1'];
}

//(after)

//{tag} and {tag}{/tag} pairs are used to delimit dynamic values in the template string
if (preg_match("/\{".$val."\}(.*?)\{\/".$val."\}/si", $this->template, $match))
{
  $this->temp[$val] = $match['1'];
}

You can see in the second block, the line comment explains why this particular action is occuring and the preg_match function - which is fairly easy to read - explains how it actually works.

3. In addition to #2, it's important to comment why certain decisions were made to use a particular function/method/style.
How many times have you looked at someone else's code and said, "Why in the world did X do it THIS way?? Didn't he/she know about function Y or Z?"
I've encountered this in my own code where, had I not written a comment, I would have wondered why I didn't do something a different way:

Code:

//curl and file_get_contents don't work on server XYZ
$datafeed_xml = simplexml_load_file(DATA_FEED.$lastDownloadTime);

The line comment tells me that I've already tried curl and a file stream and neither worked - so at least I won't go down that path again if I revisit the code a year from now (if it's still on server XYZ)

Here's one of my favorite quotes:

Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.

http://www.codinghorror.com/blog/archives/001137.html

[eluser]TheFuzzy0ne[/eluser]
I agree. If you need to document any of the code itself, the the code should be made simpler. Sometimes a line of code can't be simplified, in which case that's probably the time to add a comment to the code.

[eluser]jalalski[/eluser]
It helps to have an IDE that automates some of it. In NetBeans, just starting a JavaDoc style comment fills in all the parameter fields and return etc, which makes it very easy to slap a header on a class/function.
Generally, I avoid comments within the body of the code unless necessary.