Re: ImpressCMS SVN Repository
Posted by Dave_L on 1196873354
I agree with Rules 1-3, and would like to propose another one:
- Rule #4: All committed code must be fully documented.
In part, that means that every function has a phpDocumentor-compliant header comment, which is both correct and understandable, states the purpose of the function and describes the parameters and return value. The same applies to class properties. The header comment for a function (or a class) is intended to be a "mini user manual" for the function that provides all the information needed to call that function, without having to examine the body of the function.
I suppose this won't apply to existing code that you're modifying and don't understand well enough to add missing documentation. Ideally we could review it and figure out together how to document it, but time may not permit that.
- Rule #4: All committed code must be fully documented.
In part, that means that every function has a phpDocumentor-compliant header comment, which is both correct and understandable, states the purpose of the function and describes the parameters and return value. The same applies to class properties. The header comment for a function (or a class) is intended to be a "mini user manual" for the function that provides all the information needed to call that function, without having to examine the body of the function.
I suppose this won't apply to existing code that you're modifying and don't understand well enough to add missing documentation. Ideally we could review it and figure out together how to document it, but time may not permit that.
This Post was from: https://www.impresscms.org/iforum/viewtopic.php?topic_id=572&post_id=5188