DocumentorBundle for your Symfony2 project's documentation needs

After I acquired some inspiration from Mike Van Riel's talk about phpDocumentor2 at PHPNW12 conference, I decided to make it easier for developers to generate their PHP documentation in Symfony2 projects.

https://github.com/artur-gajewski/DocumentorBundle

Once you add DocumentorBundle to your composer.json file and update the vendors with it, you need to activate the module in the AppKernel.php file by adding the following line to the bundles array:

$bundles[] = new \Aga\DocumentorBundle\DocumentorBundle();

Now you only need to run a command in console:

app/console documentation:create

DocumentorBundle will now generate php documentation in /web/bundles/documentor folder, which you can access with your browser by going to that URI.

The bundle generates documentation only from the the bundles installed under src/ folder. What I like about the phpDocumentor2 is the way it tells you what is missing from your php classes; DocBlocks for class, functions and variables. This way you can run the command and fix the documentation until you have no error messages listed.

I also like how visually pleasant the outcome of the phpDocumentor2 is. It is nicely styles and categorized in click-to-see fashion. You can hide/unhide different variable and function types and also can see all @todo statements across the bundles.

Little ending note about DocumentorBundle, PhpDocumentor2 is required. Once they get phpDocumentor2 installable via Composer, this will be not q requirement as I will make it a dependency for this bundle.

The importance of documenting your code

Does it feel like waste of time writing DocBlocks in the code you write? Are you one of those people who believe that code documents itself? These questions seems to be a constant battle among developers and those who favor documenting code.

I have done web development for twelve years now. Along these years, as incredible as it may sound, I have never started a work related project from scratch. Instead, I always managed to get right in the middle of the development where code base was pretty much in a state of working prototype.

One thing that I noticed each and every time I joined a project, was how complex it felt to get familiar with the code base that is not well documented. It's not like I didn't know how to read the code and learn from it, but how much easier it would have been to read a short description of a function, a little more detailed one and then read the usage for each of the variables used in the method. One glance, few seconds and I was on the right track about the function's usage and dependencies.

When we live in a world with globalization as a way of doing business, we must remember that a code our competitors write might end up in our hands at some point. I have seen it many times and I have experienced it first hand how it is trying to debug a spaghetti code with no documentation, either printed or inline.

But the main important fact is, that team members can and will eventually change in a project over time. Documenting code as much as possible is your way to show your professionalism and courtesy toward your fellow co-worker. It also allows new team members to get quickly familiar and comfortable with the project's code. Time is money, who has loose money to spend on pointless code familiarizing when it could be a snap.

Documenting your code is not hard, it's not a rocket science. I encourage you to read up a great tutorial of phpDocumentor by Gregory Beaver:

phpDocumentor Tutorial

I hope this blog post will bring you some thoughts on how you can improve the quality of code you write and how much it affects your co-workers.

Until next time, cheers!

PHPNW 2012 Conference review

It's been a week since I attended my very first PHP conference in Manchester, UK called PHPNW 2012. I didn't know what to expect and what the hype about this particular conference was all about, so I started my journey to Manchester with an open mind.

I packed my clothes and gear (laptop and iPad) and headed to Helsinki-Vantaa. As I waited for an airplance, I read up The Book by Symfony2. Lately, I've been getting more and more interest toward this framework as it seems to be built ease of use in mind, but also good coding standards, latest technology and very nice templating system called Twig.

Once I arrived at the airport I was picked up by Jenny Wong, one of the organizers of the event. I shared my ride with some other developers and speakers and we headed to her house for a little barbeque party. I got to meet some local developers there as well, and so we spent the evening talking about Symfony2, composer and related things.

On friday, I attended full-day tutorial on Zend Framework 2 held by Rob Allen (@Akrabat) and Evan McCoury (@EvanDotPro). Even though I was already quite familiar with the framework, it was nice to go through it all in little more detail. We had little exercises in between chapters, which was nice activity between slides.

After the tutorial there was an evening Hackathon event, in which attendees got to join different groups working on their project. Before the conference, I was talking to Lineke on IRC about their open source project called ProTalk, so this was a great opportunity to meet them in person and start hacking on their project. The wireless connection in the premises was a complete disaster though, as it took minutes just to load Github page. Luckily there was codebase available on memory stick along with vendor dependancies, so we got to hack the code after all with a little bite of pizza and beer.

Saturday started the official conference portion. There were speeches of different topics each hour lasting for fifty minutes each. I found particular interest in talk about new PHP 5.4 features, state of PHPUnit, Twig templating, and opportunities in open source. It was information packed day and while my brain started to process it all, we spent the rest of the evening at the bar without laptops this time. It was nice to meet even more new developers and share experiences with them.

Sunday was the last day of the conference. First I learned how BBC built their website on responsive layout and then I attended a talk about phpDocumentor2 which creates nice documentation of any project based on the DocBlocks in source code.

The closing of the conference was handled by keynote of Michelangelo van Dam, as he explained how companies could pitch in into the world of open source.

I could not be happier about attending the conference and would love to attend it again next year. The location was great, everything was organized with skilled people, conference contained interesting speakers and extra activity and the one could really feel like a part of a large community.

Inspired with all the experience, I revived this blog and will write here more often now.