Home Messages Index
[Date Prev][Date Next][Thread Prev][Thread Next]
Author IndexDate IndexThread Index

Re: [wp-hackers] Inline documentation

  • To: wp-hackers@xxxxxxxxxxxxxxxxxxxx
  • Subject: Re: [wp-hackers] Inline documentation
  • From: Roy Schestowitz <r@xxxxxxxxxxxxxxx>
  • Date: Wed, 15 Feb 2006 19:51:57 +0000
  • Delivery-date: Wed, 15 Feb 2006 19:52:01 +0000
  • Envelope-to: s@schestowitz.com
  • In-reply-to: <43F3805C.2060305@skippy.net>
  • References: <43F33C8D.2010509@rcbowen.com> <80f75db0602150853o510486b3p4ea2aaa2558a1c90@mail.gmail.com> <5aa3aa0602150901y1317ec46n5e0e23e22bac9013@mail.gmail.com> <43F373EB.7000505@atl.lmco.com> <20060215191953.kkqygfrxmunkos40@banana.catalyst2.com> <43F3805C.2060305@skippy.net>
  • User-agent: Internet Messaging Program (IMP) H3 (4.0.3)
_____/ On Wed 15 Feb 2006 19:26:20 GMT, [Scott Merrill] wrote : \_____

Roy Schestowitz wrote:
Comment ought to be accumulated and always remain in tact in the
Each time release milestone is reached, run a parser which strips all
comments and publish.

Developers can fetch documented code of interest from the SVN repository,
the nightly, or a Developer Edition. It is worth using the same tactic with
debugging bits in the code. If there are none, something in development
model is probably missed.

I _strongly_ disagree with this approach. A lot of people have learned PHP by fiddling with WordPress. I've personally encouraged a handful of people to do so. I think WordPress should be making an effort to _encourage_ people to work through the code whenever they have an interest in doing so. Comments are a good way to help a new developer learn the internals.

Requiring them to fetch the "development source" seems like a gigantic
waste of time, and a real disservice.

I respect your point-of-view on this. I /would/, however, like to raise the issue of debugging, which is equally important, yet has been clearly neglected. When used excessively, much like comments (in the context of code), it slows down the program, but I its potential is currently missed entirely. As some toy pseudo-code:


 % exception handling, long list of pre- and post-conditions

if world<>same
  report using TCP
  spew out "Hello World"


You can automatically remove such padded bits. Better yet, let wp-testers
run such code and echo exceptions to Trac, or send them directly to a
server (i.e. 'call back home').

It is harmless if one remembers to remove debugging code  at the end
(suitable text editors will fold DEBUG or syntax-highlight it using dim
colours). Otherwise, as in the case of OpenOffice and Office benchmarks,
someone could compare a program which is heavily loaded with 'junk' against
a finalised release.


[Date Prev][Date Next][Thread Prev][Thread Next]
Author IndexDate IndexThread Index