[wp-hackers] Inline documentation

[Roy Schestowitz]

_____/ 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
>> repository.
>> 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:

% BEGIN DEBUG

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

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

% END DEBUG

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.

Roy