The blessing in documenting code

I’m currently working on this framework in PHP but I was very unsure about what features to add. That’s why I began to document in the code at once, but it didn’t work right. It was too many changes in the code to begin with and I didn’t really know what I wanted – so the documenting was a messy draft that had no effect and became soon outdated.

But, that’s not the whole story. A framework need a good API, and I began working with it and found that it was actually a lot of fun. Firstly I listed every method I could think of, and then I began to write the functionality of each of them including examples of their usage. This way I found a lot of things to improve on the method functionality, I got a really good flow on programming them. It resulted in a really great API documentation as well.

What did I learn?

Different projects need different types of documenting. If you are unsure about your project try a more planned approach and then when the project is finishing up – then write the documentation in code. Other projects that has a lot of repetition in how methods act(like getters and setters, or getall_xx_fromdatabase) – they are easy to document in the code as PHP Doc because you know how to implement them and what you need them for. There is no point in building an API for a site like that. It’s not about what works for you, it’s about what works for your project.

This approach works also on testing. There is no point it creating unit tests for a framework that is under developement and have no real structure in what methods return or work. If you have a project with a lot of methods where you have define what they do, you can easily write Unit Tests for these methods. But if you, as I have, a method that does a lot of different stuff – then the best way is to have a test page and test alongside documentation. Later on, when you do a change, you can check if the test page renders the right way. When you have finished you can polish this test page, and make UnitTest for every possible use case.

Learn how to be flexible in how to document. When you do it right it might be fun. But do document!

Is PHP frameworks bound for patterns?

I was looking into the code of some common and uncommon PHP frameworks, and all of them proudly showed off their implementation of MVC pattern. Some of them were using a variety of other patterns and techniques – and I was wondering, do they really have to?

I was all confused when the different frameworks had their huge folder structure and a lot of stuff you had to do in order to echo out “Hello World”. And they said it was easy and fast. The fastest and most easy is still to write echo “Hello World”.

Its ok and good to implement MVC structure on a framework – it’s almost a nessecity, because programmers all know what it’s about and can easily adjust. But don’t tell me that your framework is special when it’s not. Dont tell me that it’s simple when it’s not.

I think, on the framework I’m building and the projects I’m working on, that the framework frees me from being bound to MVC and patterns (or was it the other way around, that they bind me to use MVC and patterns?). Instead I create my own based on the needs of the site (it be an abstraction of MVC or other patterns). Frameworks, in my opinion, is for abstracting away some code and make it easy to write the application. I like thinking new and creative.

But the again. I never liked frameworks. So my vision is clouded in the matter, I admit that.

Sexy Code

Why does JavaScript get all this attention and rethinking these days? Wherever I turn my browser there is a lot about jQuery, node.js, prototype etc. Why cannot the same techniques be applied server-side, on PHP? Aint PHP sexy? JavaScript was not sexy at a point until someone made something with it and it became fantastic and easy. How did that happen? Are JavaScript developers more creative? Is it a better and more flexible language? Is it because its front end and handles interaction?

Well. I’m going to try to code sexy when I do PHP. Right now I’m writing this html parser that is neat and cool. I want to be a part of server-side language revolution with PHP. It has potential! I don’t want to hear about Ruby on Rails, .Net or Python – lets empower PHP, and get rid of all that crappy code out there.

I’ve programmed a database class multiple times, and its an evolution. This happens in every aspect of my code all the time, and that’s really a journey. Here are the database example:

First it was spaghetti.
Second time I made it in a config file.
Third time I switched out mysql with mysqli and made some functions.
Fourth time I made the database a class.
Fifth time I accessed it through a controller and DAO classes.
Sixth time around I made it a singleton and reused the connection.
Seventh time I added pconnect and it became persistent.
Eight time, then the database object extended the mysqli class.
Ninth improvement was to make a ORM expand the connection.
Tenth evolution was to make an easier access for the creation of advanced queries.
Eleventh time, I made the ORM chainable and combined more advanced queries to it.
Twelfth thing was to improve the to interact with different kinds of result sets.
Thirteenth, in the end, the chainable database singleton class extending mysqli got wrapped in a function for easy access.

How do you like this kind of code:
echo query('tablename')->columns('id, name, regdate')->where('id > 155')->orderby('name')->asc()->toarray()->html();

And the future still brings more:
– The code to support multiple different databases
– Extends the support for joins and relations
– Add better template engine to the output presentation
– Make the mess faster

That is what I’m currently working with…