JSDev: Executable comments (by Douglas Crockford) (github.com)

As much as I respect Douglas Crockford, did he just reinvent Python's Doctest (http://docs.python.org/library/doctest.html)?

Not to knock the work that's been done or disparage the author of this code or similar work that's hosted on github.

But these link's to a github repo with minimal documentation and no instructions on how to use the code are frustrating.

This does look really interesting and something that we could potentially use ... but I wouldn't know where to start without a little more documentation I'm afraid. Is it a browser extension? Where do I install it? etc.

I like the concept of the dev comments automatically being removed by minification, though, no extra buildy stuff required.

    ./jsdev < input.js > output.js

No wonder Crockford is so smart. HE LIVES IN THE FUTURE!

    /*  jsdev.c
        Douglas Crockford
        2012-01-05

Committed 2012-01-04T15:19:34-08:00

we've been doing this for about a year now, though we just use stuff like:

// debug: something %s, here

compiling to:

console.debug('something %s, here)

etc, along with some for profiling etc

In Perl, the CPAN module Smart::Comments does something similar:

http://search.cpan.org/dist/Smart-Comments/lib/Smart/Comment...

Edit: It seems backticks (``) don't indicate code, so the following is shown as `/test/`:

    `/*test*/`

(End edit.)

I personally prefer something like

    // In some entry point, sticking DEBUG on the global object or outermost scope
    var DEBUG = true; // Somehow don't minify this

    if (DEBUG) {
        // arbitrary JavaScript
    }

with `sed s/DEBUG/false/g` (simplified) or inserting `var DEBUG = false;` somewhere* to strip debug blocks from the source when compiling minified/release versions. Dead code elimination throws away debug blocks, and this method doesn't require you to pass your code through a tool every time you develop (so line numbers, etc. always match).

Yes, it's not robust, and I realize this solution is. But modifying something like Uglify or Google Closure Compiler to replace DEBUG's value wouldn't be a bad idea, I think, if you really care about strings and such not being replaced.

Something similar can be accomplished (though it's a bit more limiting) if you replace special comment tokens. For example:

    /*DEBUG*/ {
        // Debug code here
    }

I would see the use if this tool did more than replacement magic. For example, I could specify `/profile/` somewhere inside a function and it would automatically be instrumented for profiling. Or, `/count/` could increment some global variable (unique to each `/count/` instance) easily accessible and useable from a JavaScript console (perhaps based upon the containing function's name or line number?), or `/count-print/` could do the same but printing every second or every 100 calls. But even for these cases, I see myself manually instrumenting these instead of configuring a tool and sticking it in my development workflow.

*Sometimes, `var` statements (even with a constant) are not inlined by Google Closure Compiler (only minifier I am aware of which performs inlining).

    uglify --define DEBUG=true

    if (DEBUG) ...

I'm concerned that this will facilitate testing of private implementation details; I do believe that the public API is the only thing that should ever be tested. If you need to test the implementation details of your unit, then that should be pulled out into another unit which is in some way included in this main unit, and tested in that context.