Re: [PEPr] Proposal for RFC::Header Comment Blocks

Hello Daniel, DC> Daniel Convissor (http://pear.php.net/user/danielc) proposes RFC::Header Comment Blocks. DC> You can find more detailed information here: DC> http://pear.php.net/pepr/pepr-proposal-show.php?id=128 My proposal is to keep source code clear from not important information. PEAR packages are used by programmers and often due to a lack of good docs it is easier to look into the source to understand how it works. However, if sources are bloated with such comments, it becomes harder to navigate and to understand where are you at the moment. It is not uncommon situation, where one line author description worths whole class variables comments. My POV is that comments should not be misused. Text of license along with additional informative info can be supplied on the package web-page along with it description. One time meaningless comments due to CS reuirements do not help developer to understand structure of the package. Quite opposite. Current proposal. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ /** * Short description for file * * PHP versions 4 and 5 * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_0.txt PHP License * @version CVS: $Id:$ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since File available since Release 1.2.0 * @deprecated File deprecated in Release 2.0.0 */ My proposal. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ /** * Short description for file * * PHP versions 4 and 5 * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_0.txt PHP License * @version CVS: $Id:$ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since File available since Release 1.2.0 * @deprecated File deprecated in Release 2.0.0 */ Have you seen any differences? Probably took some time to understand they are the same. You do this operation every time when you open source file. Your mind is trying to recognize this image and after that you understand what you've got. Every function differs in it's visual presentation in source code, even if you'll see your code from 15m distance, most of the time you will be to say which function it is. But this is not true if there are methos headers. Because these are the same. It even worse when every property contains @var threeline comment. When navigating sourcefile, instead of leaving recognition procedure to some low-level stuff of your entity you need to stop at every comment block and consciously read it. That takes away attention from the real reason which brought you to this function. When you investigating structure of a new package you can easily loose logical chain. Pay attention next time. Comments can be reproduced from source code. Opposite is not true and in addition comments can be old, misleading or without any useful information - fillers or tribute to CS. So my proposal is keep amount of comments reasonable and leave it to developers to decide where they are appropriate. Do not enforce every line to be documented, because it probably speaks for itself. There are CS, indeed, but for I dislike idea of comments standart. My ideal representation of Header block is one with minimum info to use the package properly. Is should include PHP, package version, license type, package link and authors. Additionaly it can include short description, license text. <?php /** vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */ /** * PHP Version 4|5|9 PEAR Some_Package 1.23-Beta * * Short description for file and package * * @link http://pear.php.net/package/PackageName * @license BSD|PEAR|PHP|other (http://link) * * This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * @authors Original Author <author@example.com>, Another Author <another@example.com> * */ /* $Id$ */ t --