|
|
|
|
| Tutorial |
Chapter 1 Development Concepts
File Header Comments
File header comments should look something like those in Listing 1.3.
Listing 1.3 File header comment.
///////////////////////////////////////////////////////////////////////////////
//
// phpIRC.php3 - IRC client module for PHP3 IRC clients
//
///////////////////////////////////////////////////////////////////////////////
//
// This module will handle all major interfacing with the IRC server, making
// all IRC commands easily available by a predefined API.
//
// See phpIRC.inc.php3 for configuration options.
//
// Author: Till Gerken Last modified: 09/17/99
//
// Copyright (c) 1999 by Till Gerken
//
///////////////////////////////////////////////////////////////////////////////
You might prefer to use a bounding box created by multiline comments, which some
people tend to find more aesthetic (see Listing 1.4).
Listing 1.4 File header comment using multiline comments.
******************************************************************************
* *
* phpIRC.php3 - IRC client module for PHP3 IRC clients *
* *
******************************************************************************
* *
* This module will handle all major interfacing with the IRC server, making *
* all IRC commands easily available by a predefined API. *
* *
* See phpIRC.inc.php3 for configuration options. *
* *
* Author: Till Gerken Last modified: 09/17/99 *
* *
* Copyright (c) 1999 by Till Gerken *
* *
******************************************************************************/
Extracting Block Comments in UNIX
On UNIX systems, the following grep command extracts such block comments from the source:
grep ‘^[\\\/ ]*\*’ source.php3
15 Coding Conventions
Which style you choose for formatting your headers isn’t crucial, but the information
you choose to include in the file header is important. As shown in this example, headers
should include such general information as details about the module, author, and
so on. Items should be placed in a meaningful order (for example, it makes no sense to
include a long description and then a short description—by the time you’ve read the
long description you don’t need the short one anymore).The following list shows suggested
information as well as order:
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
