[wp-hackers] Inline documentation

[Dave Grijalva]

I totally agree here.  For both comments and debugging code.  By stripping
them from the release version, there is zero extra overhead for the end user
while still providing very worthwhile tools to the developers.  Many good
IDEs for compiled languages have supported this for quite some time.  XCode,
for example, supports multiple build profiles for development vs
distribution and allows the developer to leave large quantities of debug
code in the source, while stripping it automatically at compile time.

Also, it should be noted that the Zend engine tends to be very efficient at
removing comments and extra whitespace.  So even if some comments do get
left in, the overhead cost is minimal.

-dave

On 2/15/06, Roy Schestowitz <r at schestowitz.com> wrote:
>
> _____/ 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
>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>