[wp-hackers] Proposal for a function commenting convention

[Peter Westwood]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Andy Skelton wrote:
> On 10/16/07, Andy Skelton <skeltoac at gmail.com> wrote:
>> Would everyone on this thread please pause your typing and take a
>> reality pill. If you think it is important, do the work and submit a
>> patch.
> 
> One more thought: an excellent commenting convention may evolve, but
> if you want something enforced you must convince the commit funnel
> that no function should be added or changed without the matching
> PHPdoc being updated. If you are successful in this campaign, the
> funnel will either push back on patches missing PHPdoc updates, or do
> it themselves. If you are unsuccessful, they will neglect enforcement
> and allow non-conformance.
> 

+1 to this.

If future I will be tagging all patches for new functionality without
documentation with needs-docs and they will drop lower on my to-commit
list than stuff with docs.

For small isolated bug fix patches I will obviously commit without docs.

However if a function needs changing and the changes are large I will
prefer patches with docs.

westi
- --
Peter Westwood
http://blog.ftwr.co.uk
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHFR2rVPRdzag0AcURAlbaAKCG2tqA104ztNU24NaEw2OZrd+wXgCeKhq3
CbRCBVO/sP/Ifpm1/lrPkCY=
=LTz1
-----END PGP SIGNATURE-----