Standard change comments

Question

I am looking for some direction as to a standard format for commenting changes in PHP. Continually while working with an assortment of developers on large scale projects, comments run wild and in most cases changes are either poorly commented or not commented at all.

Here is an example, please feel free to expand on it:

/**
 * Author: [first and last name]
 * Date Changed: [YYYY-MM-DD]
 * Description: [description]
 */

Q: Does anyone know of a standardized way of commenting changes in PHP?

Answer 1

Such things should not be put into file comments. Use revision control software to store all versions of your file (not just the latest). Never allow developers to work without it. Such software allows you to do much more with source code:

• You can find who changed each line of the file
• You can revert file to previous (or working) version
• You can create different branches of your source and merge them automatically
• You can automate building of your software and run tests automatically
• Backup your source repository and you'll never lost your work
• ... and more

Answer 2

Besides using source control, comments should generally be focused on to the current state of the source code, not provide detailed history, except perhaps for explanatory context.

Comments should describe the how and why of a program and not be an administrative scratchpad or historical fill-in form. It is how one engineer communicates with another engineer—or maybe remind himself/herself—what the conceptual model is. This could explain the basis for an implementation such as its philosophy, expected usage, or world view. But—as you well know—engineers can't be relied to be clerks.

I think we've all seen source like this:

/*
 * Function:  (fill in name)
 *
 * Returns:  (fill in type)
 *
 * Date:  (current date)
 *
 * Revision (revision number)
 *
 * Author:  (your name or initials)
 *
 * Description:
 * (describe function)
 */

where no one has filled in any but the most useless details—if at all.