I have stared into the belly of the beast that is the Zend Framework documentation and have discovered the following truth: there always seems to be two ways to do something. For someone just starting out learning a framework (never mind their actual level of experience with PHP itself) this is not a good thing. For example, let’s look at creating a new base controller to extend controllers off of. Via twitter I found the following ways:

• no, don’t do that, use custom action helpers
• sure, just put it somewhere and use autoloading to find it

So I proceeded to start digging around and figure things out. Hrm, an action helper is not what I need, so let’s create that new base controller. Oh, you mean you can have more than one way to lay out your project, even if you are using Zend_Application? How come it’s not finding the new controller even though I put it in a common place. Why won’t this work?!? DAMNIT, I AM GOING TO QUIT PROGRAMMING AND RUN A DADDY DAY CARE OUT OF MY HOME.

Fortunately the custom routing thing was easier to figure out. Hey, here’s an example of adding code to your bootstrap. Oh wait, I’m using Zend_Application so things are different. WTF, I am overriding my existing routes and everything is broken?!? You can put this stuff in XML?!?! But I am using the .ini format…. Nice, MWOP pointed me in the right direction. Good thing he’s on twitter.

Look, I’ve talked about this before. It’s awesome to have lots of documentation. The Zend Framework documentation is awesome…but seems to only have 80% of the solutions I was looking for. Digging around using Google just seemed to point me at the same 80%-complete documentation.

Writing documentation is a thankless task, so do not interpret my comments as a slam against those who are contributing. I work best when I see FULL examples on how to do something, and then I can “extend and embrace” that to produce the customized solutions I always end up needing. My complaints are solely my own, which is why I usually blog the solutions when I come up them. I certainly cannot be the only one having problems sifting through the documentation.

As someone who had invested a lot of time in another framework, I am painfully aware of how much you take for granted when using a familiar tool, and then try to help people solve a problem. My own experiences have ranged from “you are most definitely doing it wrong” to “I’ve never done it that way, and I can see how that will work”.

Special thanks to @weierophinney, @elazar and @andriesss for their actual help and offers of help as I stumble around using Zend Framework.

What has prompted this incredibly brilliant stating-of-the-obvious? The reaction by those in the Twisted community over Facebook’s pre-emptive strike in the non-blocking Python-based web server space by open sourcing a framework they are using internally called Tornado. Why are the Twisted folks getting all twisted (look how funny I am!) up about this? Like any good Open Source project for people who are interested in Getting Things Done, Tornado is dissing Twisted by basically saying “yeah, we thought about using Twisted but it wasn’t easy enough for us to use and we think it sucks”. I’m pretty sure I’m paraphrasing here, but you get the idea.

Now, I have looked at Twisted and have come to the following conclusions:

• It looks awesome
• It is built for people who are supposed to understand what they are doing
• The documentation sucks
• The examples on how to build anything of any significance are, to this developer, non-existant and/or difficult to find without shelling out for a possibly very-outdated book

Contrast this with Tornado. I’ve looked at Tornado and have come to the following conclusions:

• It looks awesome
• It is built for people who are supposed to understand what they are doing
• The documentation is inside the comments on the code which sucks only if you’re not into reading the code
• It includes a sample application so you can see something other than Hello World

Am I biased towards Tornado? You bet. Why? Because as hard as I tried, I could not find USEFUL documentation on how to build things using Twisted. Maybe I didn’t use the right search terms. Maybe I didn’t dig down enough links deep on the Twisted site. Maybe I didn’t fully understand the terminology or architecture of Twisted and how they different components speak to each other.

I’ll tell you this though: I am not having any such problems with Tornado. This is coming across as a criticism aimed towards Twisted, and I suppose that’s fair. I’ve noticed complaints from the Twisted community which really amount to whining. I understand that attitude totally. I’ve been there, when faced with competition that just might be doing a better job then I am doing. But complaining that Facebook should’ve simply fixed up Twisted instead of writing their own is not productive. Productive is understanding that Facebook looking at Twisted and said “this is not for us because *we* don’t find it easy enough to use” is a sign that something serious is wrong with Twisted’s documentation. You could have the most awesome non-blocking web server available, but if people with who WANT to use it can’t figure out HOW to use it, well, what can you say to that? Only the most dedicated open source contributors would’ve done that. Most will say “meh, I want to do this myself so I understand it” and then Twisted will die an obscure death while Tornado plunges forward gaining mindshare amongst people interested in the type of applications you can build with this technology. In my opinion, it’s all because of the lack of clear, freely available documentation for Twisted.

If there is an online source BETTER than the Twisted site, please share the link love in the comments so I can try and do a better comparison of the two at a documentation level. For someone like me, who is new to Python but old to the idea of web frameworks, I think that would be the fairest comparison.

MySQL over an SSH tunnel

I certainly can’t be the only person who has to do development (or refactoring) work involving databases that have GB of data in them. It’s not even remotely practical to copy it over to my laptop, and taking a snapshot is pretty much impossible given the relationships between the tables. It would be 3 times the work to create a tool to give me a snapshot that includes all the proper related records. How do people handle that anyway?

So I discovered via my favourite pair-program-via-IM partner the technique of tunnelling to MySQL over SSH. It couldn’t be easier:

ssh -fNg -L3310:127.0.0.1:3306 user@server.domain.ext
mysql -h127.0.0.1 -P 3310 -u user -p database

You can use whatever port you want at your end, but the key here is telling SSH that you want to map port 3306 on the remote server to a specific port at your own end.

The only downside I’ve seen is that when I was pounding on a remote server with a very involved query that the remote server started writing MySQL tmp files to disk. Files so large that they started to trigger our Nagios monitoring process that look at free drive space. Maybe I shouldn’t do that on a production server. Heh.

Use an editor that supports remote debugging in PHP

I took a Twitter poll and asked how many people actually use debugging tools like xDebug and was surprised by how many don’t. I have used them off an on (more on these days) and now that I’m using vim I have also started debugging stuff inside of vim. Is there *nothing* you cannot bend and twist vim to do for you?

This just further reinforces my recommendation that whatever editor you do decide to use every day, learn it inside and out. Right now I’m trying to break myself of the habit of using the arrow keys to move around in vim, instead relying on the hjkl home row keys to do so. Debuggers are so common in other languages (Ruby and Python have an awesome interactive console to act as a debugger for you) there is no reason except for, I dunno, laziness and an unwillingness to learn how to add an extension to your PHP install, to not at least try using xdebug.

Don’t procrastinate, read the documentation

A side project I’ve been working on has some of the tightest production-level PHP code I’ve ever written in it. Why? Because I took the time to dig into the documentation of the newer features in Cake to see how they apply to the work I’m doing. Containable behavior that is now part of the core. Johnathan Snook’s Multiple Validation behavior. Fat models and skinny controllers. Reusable elements in your pages. Pestering Nate and Garrett via IM to confirm my suspicions on how to tackle certain problems “the Cake way”. It’s amazing what happens when you stop to think about all the techniques you’ve learned and then figure out the best way to weld them all together to solve a problem.

Again, I’ve said this before and will continue to say it: making the effort to fully understand the tools you are using (that includes editor AND programming environment) can only make you better.

If the documentation is bad, don’t even bother using it

My IM pair-programming partner once said to me “Chris, if the documentation is shit then don’t even think about using it.” Lately I’ve seen the wisdom in that. If the documentation is lacking, just forget about using that tool. Of course, if you *do* have the skills to dive right into it and figure out what’s going on then this technique probably doesn’t apply to you.

Learn your version control system, or else have it decide your fate for you.

There is incredibly well-written documentation for what I call the Big Three (CVS, SVN and Git) open source version control systems. For the love of Wotan, go and learn the one you are using beyond how to commit a change. And if you AREN’T using a version control system (no, renaming files to index.php.old.frank is NOT version control) then you should stop calling yourself a programmer. Seriously.

Peer code reviews are good, not bad

Even if it consists of taking 15 minutes to talk with your boss who wrote stuff and says “but I’m not really a programmer” so he understands the changes (for the better that you are making, it pays off huge in the end. Especially when you know they will be going back in to tweak things as they play with the code you wrote.

That’s all I can think of for the moment. What programming techniques or tools have you come across that have made your work go faster or help you produce better code? Let me know in the comments.

As a committed user of open source technologies, the difference between me using something and not using something is the documentation. Is there documentation for it? Is it easy to find? Does it answer my questions? Is there someone I can call an idiot if I disagree with the level of documentation? These are all very important questions.

My involvement with CakePHP has opened my eyes in terms of what people consider documentation. Me, I’m the type who learns from examples that come with explanations. While API documentation is great, it only becomes useful to me once *I* can figure out how to do something useful with this new technology. I see people on the mailing list for Cake asking for the source code to a sample application, which I immediately file away in my head as “looking for answer to their homework”, and move on. Maybe that’s unfair, but it’s more a reflection of the fact that I tend not to learn anything from having the source code for an application. I learn by getting in there and DOING SOMETHING and figuring out why this goddamn thing is not behaving properly and who do I know who can help me with this problem etc. Learning by mooching, I call it.

So, back to CakePHP. CakePHP had acquired the reputation that the documentation for it sucked. While I did not share that opinion, I can see why people say that. Because most coders are lazy. Seriously. They want solutions handed to them in a form that they can just drop into their application and then get onto the next problem. There are definitely times when I wish someone else could just write this goddamn “alter the football game stats form dynamically via Ajax and send the results to the XML database” code for me. Inevitably, I build the code up from an example stolen via Google into something that both works and that I understand fully. However, most of the time I am content to figure stuff out on my own and ask for help only when stuck. I’m not lazy, but maybe I’m suffering from a bit of the Lake Woebegon effect.

So, things are much better in terms of documentation for CakePHP. Whereas we used to have a manual that only covered 1.1, we now have the amazing CakePHP cookbook that covers both 1.1 and 1.2. If that’s not enough, well, you might actually have to do a little thing I like to call “research”. This gets us to the point of this blog posting. Sometimes you have to stop being lazy and actually think about where you could find an answer.

There are no shortage of blogs that talk about CakePHP. Some of them are even good. Maybe you like the code examples I put up here. People seem to like them enough to comment, so maybe I’m doing something right. Google is your friend to track down blogs that have exactly the type of information that you need: small examples with explanations about how they work.

The CakePHP mailing list is done via Google Groups, so all those posts where I make fun of people for no reason other than my poor self-esteem can be found with a few keywords. But there are a lot of great tips on how to accomplish things using Cake, so a search of the google group will find lots of good information.

The Bakery is another good source of CakePHP info, consisting of all sorts of small articles along with comments. It has a search function as well, but could easily be considered YACB (Yet Another Cake Blog). Again, perfect for people with the same learning style as me: short examples with explanations of how it was done.

Finally, we come to one of the more unorthodox documentation sources: the unit tests for CakePHP. CakePHP has some really good unit test coverage, although I sometimes wonder if you can really say that a piece of code works properly if it passes all the unit tests associated with it. This is by no means a phenomenon limited to CakePHP, it happens everywhere there are unit tests. Sometimes you can’t figure out a test that makes something break. It happens, so please do not misinterpret my thoughts on this. Unit tests are good, and the amount of tests that CakePHP has in place is awesome and perfect example of a cohesive development team. Automated testing is a goal worth striving for, don’t let anyone else tell you otherwise. I’m in the early phases of automated testing for a work project on the integration side of things because I’m tired of always running through the same damn tests by hand all the time to make sure something that I wrote didn’t break things. Tips on what good browser-based solutions are out there would be appreciated. Other than telling me to use Selenium. A solution that is tailored to the framework I have been forced to use would be even better.

Okay, back on topic. Since the unit tests cover so much of what CakePHP can do, what better way to see examples of how to actual do things? My work on fiddling around with new console functionality showed me that I had no idea of how to create unit tests for my console work. That led to discussions with people on the best way to do testing of console functionality. Which leads to changes in the console code itself to make it easier to test certain things. But at least when I’m ready to get back to doing that console work I can see if doing testing for it has become easier.

So, having been told all the stuff above, how can anyone who is not simply lazy say that the documentation for CakePHP sucks?!?