

JSDev: Executable comments (by Douglas Crockford) - amasad
https://github.com/douglascrockford/JSDev

======
strager
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).

~~~
tav
schmerg and I added support for this in UglifyJS about a year ago. Use the
define parameter to define values for constants, e.g.

    
    
        uglify --define DEBUG=true
    

It will then replace all uses of the DEBUG symbol to true. And when you set it
to false, it will even strip away dead code like:

    
    
        if (DEBUG) ...
    

We even added support for define-from-module which allows you to specify and
use the exported symbols from a nodejs module instead of defining them on the
command line. I tend to have dev.js and prod.js setup for this purpose.

Hope these features address your requirements. Apologies if we didn't make the
feature visible enough. It's documented on the UglifyJS frontpage...

------
ruethewhirled
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.

~~~
amasad
Documentation with examples in the code comments:

[https://github.com/douglascrockford/JSDev/blob/master/jsdev....](https://github.com/douglascrockford/JSDev/blob/master/jsdev.c)

Keepin' it real, a tool about comments must have documentation in the comments
;)

~~~
ruethewhirled
Yeah I noticed that but in what context can I run this other than command
line? I assume its C code but how do I get it to work in the browser? or is it
something you'd use in node.js? Guess it's just over my head

~~~
amasad
A program is read from stdin, and a modified program is written to stdout.

[https://plus.google.com/118095276221607585885/posts/CTZ7BNx7...](https://plus.google.com/118095276221607585885/posts/CTZ7BNx7a8z)

------
portman
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

~~~
benatkin
He didn't specify a time zone in his comment but the commit sure as hell has a
time zone. The date in the comment could be UTC.

------
ScottSauyet
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.

------
josscrowcroft
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.

~~~
charliesome
You type `make jsdev` and away you go:

    
    
        ./jsdev < input.js > output.js

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

[http://search.cpan.org/dist/Smart-
Comments/lib/Smart/Comment...](http://search.cpan.org/dist/Smart-
Comments/lib/Smart/Comments.pm)

------
tjholowaychuk
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

~~~
tjholowaychuk
though I should note I now mostly use <https://github.com/visionmedia/debug>
because when a noop function invokes millions of times a second who cares :D

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

~~~
oinksoft
This doesn't really intersect with doctest as far as I can tell. That is a
rather simple feature, while this is complicated.

You might be doing something wrong when your comment-specific syntax _itself_
has comments, but I'm probably not the target audience for this tool.

~~~
eropple
> I'm probably not the target audience for this tool.

Who is?

