Just wanted to take a quick poll and see who uses phpDoc.

I used to look at code documented with phpDoc and think it was ugly (I'm a freak about neat code ). But I started to use it about a week ago and I'm really starting to like it.

Other than making it extremely easy to generate documentation, it helps me remember my own functions If you've ever had the pleasure of coding large projects with lots of separate files, modules and functions -- you know you can easily get lost once you move from one major part to another.

Note: This is a public poll

I've not used it, although I don't think I've worked on anything big enough to merit it so far. I fit in the 'I've not used used it, have a rough idea what it does, but haven't bothered to investigate further' category. Used javadoc on a collaborative project last year for Uni, but never phpDoc. I remember my functions by adding small comments here and there.

The Lazy Mans Tool.

Not for me!!! As you mentioned, I also like clean code and I detest anything that manipulates my way of thinking.

I don't think it's ugly anymore. The only thing that I find a bit ugly is when there are 4 lines of phpDoc blocks for one variable. For example:

PHP Code:

    /**
     * @access private
     * @var object Configuration settings
     */
    var $CFG;


    /**
     * @access private
     * @var object Common functions
     */
    var $FUNC;


    /**
     * @access private
     * @var object Event handler
     */
    var $Events;


    /**
     * @access private
     * @var object Database driver
     */
    var $DB;


    /**
     * @access private
     * @var object Query builder
     */
    var $Query;


    /**
     * @access private
     * @var array System options and settings
     */
    var $options;


    /**
     * @access private
     * @var object User session handler
     */
    var $User;


    /**
     * @access private
     * @var object Template handler
     */
    var $TPL; 


Those 40 or so lines (excluding the whitespace) would normally be 8.

But I've gotten used to it. I usually use jEdit to collapse most of the phpDoc comment blocks anyway.

and what was wrong with good old fashioned manual entry?

It takes more effort The manual way, you'd have two things to update every time you wanted to make a change. Not to mention the overhead of taking care of the actual packaging of your documentation. And you're more likely to update your documentation while you're down and dirty with the code, instead of having to dig into some obscene HTML.

Then to anyone else just browsing code, all the information is right there -- they don't even need to open up the docs and browse to any particular page to get the information they need.

I have been using it for the past 18 month or so.

The good points of it are easy to see.

I am new at your place and have to work out what you have been doing. Since you commented all your methods I can instantly get the jist for what your doing and how its been done.

Without this my hack time has just increased ten fold.

So sure if your not putting hundreds of lines of code in your scripts then you may find it a little overkill.
But every good programmer should also be aware that it is good practice to comment your code.

If you dont comment your work then just remember you have only done half your job.

I dont suppose you UML your stuff aswell do you Chroder? if so what patterns if any do you find you use over and over again.

Ibbo

I dont suppose you UML your stuff aswell do you Chroder?

Not at the moment. I've looked into it somewhat, but I prefer to jot down my ideas differently (I've got a whiteboard by my desk with a bunch of scribblings on it). I really should give it a try from the get-go.

If not for planning, I probably would take the time to make the models afterwards so others could visually see the application 'frame'.