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!