I currently write docblocks for everything I code.
It's crazy how much time I spend on them and sometimes they are confusing because the specs change and I keep forgetting to add/remove/update something in a docblock when I rewrite some part of the code it documents (I'd say between 10-20% of my commits are docblock updates).
I believe brief or even no documentation may be the best approach until you are on the verge of releasing a stable version.
While you are on developing and testing mode, it seems a better idea to forget about comments and focus on modularity.
After all, Why would I need comments if all the rest of my team sees is an interface satisfying a previously established and well defined contract? That's why docblocks should be only documenting public interfaces, some kind of dump taken from the part(s) of the contract they implement.
I'd consider instead other top priorites on those phases:
- Keeping an homogeneous codebase in regard of design and coding guidelines and conventions.
- Re-factoring before it becomes a problem
- Writing neat unit and integration tests
And, the most important:
- Keeping a channel open with the client, constantly feeding guided demos and prototypes showing your progress to make sure you are on the right track and you didn't get it backwards, updating specs and being realistic about what can be done and what not in which time frames with the provided resources.
It's crazy how much time I spend on them and sometimes they are confusing because the specs change and I keep forgetting to add/remove/update something in a docblock when I rewrite some part of the code it documents (I'd say between 10-20% of my commits are docblock updates).
I believe brief or even no documentation may be the best approach until you are on the verge of releasing a stable version.
While you are on developing and testing mode, it seems a better idea to forget about comments and focus on modularity.
After all, Why would I need comments if all the rest of my team sees is an interface satisfying a previously established and well defined contract? That's why docblocks should be only documenting public interfaces, some kind of dump taken from the part(s) of the contract they implement.
I'd consider instead other top priorites on those phases:
- Keeping an homogeneous codebase in regard of design and coding guidelines and conventions.
- Re-factoring before it becomes a problem
- Writing neat unit and integration tests
And, the most important:
- Keeping a channel open with the client, constantly feeding guided demos and prototypes showing your progress to make sure you are on the right track and you didn't get it backwards, updating specs and being realistic about what can be done and what not in which time frames with the provided resources.