As programmers we’ve probably all learned that documenting your code is a must. I’ve always did this, because my superiors demanded it, but more and more I’ve only documented lines that I thought would confuse others who read the code. If I felt like doing my job well I’d put up a function description, but usually I thought they were pretty obvious, especially for short functions, and I never bothered with PHPDoc.
I never understood why we should bother with PHPDoc. The auto-documentation generated from it is pretty horrible and to clearly state the @return and the @param seemed to me like overkill for any programmer who would read the code (in almost all functions it’s very obvious). And then I started working with Eclipse…
Before I had never thought I would need an IDE for PHP, notepad++ has always served me perfect. But as I observed an old friend of mine use Eclipse for PHP, I noticed the ease of especially seeing what a specific function does, and to be able to instantly go to it to see what the hell your colleague did this time. Auto-completion is also handy and guess what: all these splendid functions depend on the correct use of PHPDoc!
The conclusion is that using Eclipse makes our work easier, especially for code we work on in a team or open-source code that you need to figure out. And Eclipse is only really easy if the code you are programming on is properly documented using PHPDoc. Once you are using Eclipse, you’ll also really want to document your own code, since otherwise you can’t fast-jump to your own functions or auto-complete with objects, etc.