Documentation for large or small Projects with PHP ?

Question

Hi,

we are talking a lot about documentation for programmers in the moment. How do you handle this part?

What is the best method to introduce a new team guy into an "large" PHP Project. What does a new guy need?

My thoughts so far:

• good source code
• api documentation generated through phpdoc
• clear coding style / guideline

Some kind of paper/wiki.. with information about the infrastructure (database, firewalls..)

What else do you provide if you have to hand over your project to someone else (possible not as good as you in php)..

Do you create something like " to add an function to read out server data, put in Model xYZ?"

sorry for my poor english :)

Answer 1

You should consider using all three of them.

Try not to over-complicate your documentation, however: the harder it is to keep it up to date, the more likely it will be unmaintained. IMHO, the bare minimum for introducing a codebase to a new programmer is a coding guideline (how to call your variables, how to call your classes, are you using hungarian notation?) and phpdoc. If your code heavily utilizes third-party libraries and a large configuration file, write a small PDF which covers the steps to make your code work on a bare, new machine.

If you are using Unit tests, remember to document those, too.

Even given these, expect frequent phone calls after abandoning your codebase to a new coder. What seems logical and clear to you likely isn't for the new guy.

Answer 2

If the project has APIs then probably I'd provide sample usage, examples etc. in addition to others.

Answer 3

Documentation is good - but think of it as a guide. It shouldn't be written to teach programming and it shouldn't be a document that is easily written out of date.

The one thing I've needed consistently whenever I join a new project is to know where the code is located and how to access it. Matching lines of code to a functioning development or staging environment opens the door quickly to experimenting and discovering the "pattern" of the previous developers.

If I can make small tweaks in an interface, then I've cracked the nut and can begin to work my way backwards towards the data.

But then I'm used to coming on board projects that have little or no documentation. Not everyone is comfortable with that.

Answer 4

I code for a medium-sized codebase that is almost wholly the product of the only other programmer's work (I'm the new guy). We have auto-beautified documentation from API phpdoc comments and in-version-control best practice text files. I would give up both of those for: more extensive in-line comments, and some kind of automated testing.

I generally find api documentation good for building new features, but not especially useful for hunting down bugs, which would only really be explained well by inline comments.

So in my own work I try to lay out the behavior of new code in comments before I touch lines of code. I want to move to Test Driven Design as well, but haven't really gotten to that point yet.

And yeah, I'm a competent coder, but the size and complexity of the codebase and the fact that most of the code was created by someone else means that I frequently have to go to him for explanation on potential sources of bugs. So if you're really invested in making the codebase live on after you've moved on, consider making yourself available as a resource if you can.

One last thing that I consider essential is git (or mercurial, or some other D.V.C.S.), for the documentative commit history and the potential web-interface to the code that can come with them.