Coding Standards

I have just amended the CODING_STANDARDS file in the PHP distribution. If some of you have a few minutes here and there over the next couple of days, I would very much appreciate if you could go through the modules that you are involved with and add these comments. Keeping the documentation current and accurate is very important and we need a structured approach to making sure that this happens. Keeping the function prototypes and one-line descriptions with the code itself is in my opinion the best way to ensure that if someone changes a function, that the associated documentation ends up getting changed as well. Documentation and Folding Hooks ------------------------------- In order to make sure that the online documentation stays in line with the code, each user-level function should have its user-level function prototype before it along with a brief one-line description of what the function does. It would look like this: /* {{{ proto int abs(int number) Return the absolute value of the number */ void php3_abs(INTERNAL_FUNCTION_PARAMETERS) { ... } /* }}} */ The {{{ symbols are the default folding symbols for the folding mode in Emacs. vim will soon have support for folding as well. Folding is very useful when dealing with large files because you can scroll through the file quickly and just unfold the function you wish to work on. The }}} at the end of each function marks the end of the fold. The "proto" keyword there is just a helper for the doc/genfuncsummary script which generates a full function summary. Having this keyword in front of the function prototypes allows us to put folds elsewhere in the code without Optional arguments are written in [ ]'s. Like this: /* {{{ proto /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]]) And yes, please keep everything on a single line, even if that line is massive. -- PHP Development Mailing List http://www.php.net/ To unsubscribe send an empty message to php-dev-unsubscribe@lists.php.net For help: php-dev-help@lists.php.net