G.1. Comments

Every file should start with a comment block describing its purpose, version, author, and a copyright message. It should be a block comment in the style below.

/*
** File: test
** Description:  This is a test program
** Version: 1.0
** Created: 1/1/2004
** Author: Leon Atkinson
** Email: leon@leonatkinson.com
**
** Copyright (c) 2000 Your Group.  All rights reserved.
*/

Every function should have a block comment specifying name, input/output, and what the function does.

/*
** Function: doAdd
** Input:  INTEGER a, INTEGER b
** Output: INTEGER
** Description:  Adds two integers
*/
function doAdd($a, $b)
{
    return(a+b);
}

Ideally, every while, if, for, and similar block of code should be preceded by a comment explaining what happens ...

Get Core PHP Programming, Third Edition now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial