Question

I have designed a web app, this application contains not only some complex controllers, models and views but also some custom libraries and a database.

On top of this there is an ajax layer so: javascript functions and their related server side functions.

I’ve developed this app by myself and I want some way to ensure that 1 year down the line, if someone else picks it up there is some reference to the logic flow.

Are there tools for this? Has anyone had this issue before?

Answer 1

A good beginning would be to start using PHP Documentor (PHPDoc) before your code base gets too large. Even then, it’s not too hard to go back and tag your classes, etc. PHPDoc will crawl the code base and produce documentation, typically a web-based (HTML) set of docs, but you can also produce PDF and more. The functions, methods, classes, etc. will have links to related elements of your code. I say before it gets too large, because you will want to go back and add comment tags to enhance the output of the documents. PHPDocumentor (PHPDoc) can be found here http://www.phpdoc.org/
, and information and tutorials can be found all over the web. If you have gone this far with PHP then surely you must have noticed comments like this…(doc blocks)

/**
 *@todo something I need to do
 *@param [type] [$varname] [description]
 *
 */

These tags/DocBlocks are to be parsed by PHPDoc, and are very useful…Most IDE’s too are very friendly to using DocBlocks and will sometimes enhance code hinting, etc. based on the DocBlocks in your code.

For the Database…there are many tools and teqniques but here is one suggestion…

The database can be described by tools that will build diagrams. For instance, when using MySQL, you could install MySQL Workbench, and this will then give you the tools to connect to the database and build a diagram similar to the picture on this page…
http://forge.mysql.com/wiki/MySQL_Workbench, plus many other tools for reverse-enginerring and/or designing, tools for ORM, and more. Sometimes to just diagram and existing DB can be very useful especially when there are many relationships. MySQL Workbench will give you the option to send the diagram to PDF or an image. All very useful.

Not only will this help future developers, but these tools will help yourself too. We’re all surprised to realize what we forget after a few weeks, months, etc. of not looking at the code. Even a busy weekend can make for a slow start again on Monday morning.

For my last suggestion…and I will be simple here, but look into bug/issue tracking. There are many online or you can install your own. Some go along with version control (like at GitHub, Unfuddle, BitBucket, etc.)…or you can install your own. I find Bugzilla is pretty easy to install if your using Ubuntu it’s right in the repository and installs with ease.