Question

I have always been for documenting code, but when it comes to AJAX + PHP, it’s not always easy: the code is really spread out! Logic, data, presentation – you name it – are split and mixed between server-side and client-side code. Sometimes there’s also database-side code (stored procedures, views, etc) doing part of the work.

This challenges me to come up with an efficient way to document such code. I usually provide a list of .js files inside .php file as well as list of .php files inside .js file. I also do in-line comments and function descriptions, where I list what function is used by what file and what output is expected. I do similar tasks for database procedures. Maybe there’s a better method?

Any ideas or experiences?

Note: This question applies to any client+server-side applications, not just Javascript+PHP.

Answer 1

I think it’s best to take a hierarchical approach.

For api-level documentation like on the function and class level, write inline documentation in the code and generate html documentation out of them using the many documentation tools out there (JSDoc, phpDocumentor, OraDoclet, etc). Bonus points if your doc tools can integrate with your source control tools so you can jump to specific lines of code from your api docs.

Once you have your doc tools in place, start generating the documentation as part of your build process (you have a build process, right?) for each new build and push the documentation to a standard web location.

Once these api docs are online, you can create a wiki for high level documentation such as browser->web->db interactions, user stories, schema diagrams, etc. It’s best to write in brief prose or bullet points for high level documentation, linking to api docs and source control when necessary.