I do not know for how long I have been avoiding updating my old PHP projects and dig into them for getting them to the new standards. But trust me – reading your own code thinking ‘what the hell did I think while writing that’ is not funny. I spent yesterday in rewriting most stuff due to hardly any documentation…

Write documentation. I am not talking about big documents explaining how to use your code. This is my standard comment by now, found in every function (as already seen with JavaDoc):

MyExampleFnc($a as string, $b) {
/*************************************
Function:      My example function
Description:   This is just an exampe
               that does nothing.
Parameters:    $a - string, example input string
               $b - variant, another example
Output:        Function does this and that...
**************************************/
...
}

The comments written here are quite simple: Function is just the verbose name of the function as I tend to forget my own abbreviations. Description is exactly what it says – A short description on what the function does. Parameters is a list of arguments that are passed to it alongside with their description in one or two words. Finally the output is what the function is expected to return. That way it is possible to rewrite every function without much hassle as you know what it should do. Do not waste your time – do comments :)