Document source code while programming is the best way to do it. This helps other programmers as well as your futurte me. Documentation needs to be useful.
For example, document a flow is good:
<?php
// Store original image. // good
$...
// Crop image. // good
$...
// Store cropped image. // good
$...
Describing a for-loop that it is a loop is bad:
<?php
// It's a loop. // bad
for(...){
Describe not only the what but also the why. It’s not helpful knowing that something should be changed. Knowing why something should be changed is more informative.
Especially on negative comments the why is important.
// Do not use this.
Why is it not good to use this code? It’s fine to mark something with not but also add a reason.
// Do not use this because it goes the long way. Use xyz() function instead.
This example is more detailed about the why not.
The same goes for FIXME comments. Why should it be fixed? What is wrong with this code?
Command-line applications
For command-line applications it’s good to have an overview of all available commands. Mostly by using -h or --help argument.
I use Ronn to build manual pages from markdown-based source. For example see mbrew(1) manual page. Ronn not only creates an HTML manual page but also for man itself.
