5 ms·

JSDev: Executable comments (by Douglas Crockford)

34 points by amasad 15y ago

rpwilcox 15y ago
As much as I respect Douglas Crockford, did he just reinvent Python's Doctest (http://docs.python.org/library/doctest.html http://docs.python.org/library/doctest.html)?
- oinksoft 15y ago
  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 15y ago
    > I'm probably not the target audience for this tool. Who is?
ruethewhirled 15y ago
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 15y ago
  Documentation with examples in the code comments: https://github.com/douglascrockford/JSDev/blob/master/jsdev.c https://github.com/douglascrockford/JSDev/blob/master/jsdev.... Keepin' it real, a tool about comments must have documentation in the comments ;)
  - ruethewhirled 15y ago
    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 15y ago
      A program is read from stdin, and a modified program is written to stdout. https://plus.google.com/118095276221607585885/posts/CTZ7BNx7a8z https://plus.google.com/118095276221607585885/posts/CTZ7BNx7...
josscrowcroft 15y ago
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 15y ago
  You type `make jsdev` and away you go: ./jsdev < input.js > output.js
portman 15y ago
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 15y ago
  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.
tjholowaychuk 15y ago
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 15y ago
  though I should note I now mostly use https://github.com/visionmedia/debug https://github.com/visionmedia/debug because when a noop function invokes millions of times a second who cares :D
lepht 15y ago
In Perl, the CPAN module Smart::Comments does something similar: http://search.cpan.org/dist/Smart-Comments/lib/Smart/Comments.pm http://search.cpan.org/dist/Smart-Comments/lib/Smart/Comment...
strager 15y ago
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 15y ago
  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...
ScottSauyet 15y ago
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.

34 points by amasad 15y ago

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

oinksoft 15y ago
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 15y ago
  > I'm probably not the target audience for this tool. Who is?

ruethewhirled 15y ago

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 15y ago
Documentation with examples in the code comments: https://github.com/douglascrockford/JSDev/blob/master/jsdev.c https://github.com/douglascrockford/JSDev/blob/master/jsdev.... Keepin' it real, a tool about comments must have documentation in the comments ;)
- ruethewhirled 15y ago
  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 15y ago
    A program is read from stdin, and a modified program is written to stdout. https://plus.google.com/118095276221607585885/posts/CTZ7BNx7a8z https://plus.google.com/118095276221607585885/posts/CTZ7BNx7...

josscrowcroft 15y ago

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 15y ago
You type `make jsdev` and away you go: ./jsdev < input.js > output.js

portman 15y ago

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 15y ago
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.

tjholowaychuk 15y ago

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 15y ago
though I should note I now mostly use https://github.com/visionmedia/debug https://github.com/visionmedia/debug because when a noop function invokes millions of times a second who cares :D

lepht 15y ago

In Perl, the CPAN module Smart::Comments does something similar: http://search.cpan.org/dist/Smart-Comments/lib/Smart/Comments.pm http://search.cpan.org/dist/Smart-Comments/lib/Smart/Comment...

strager 15y ago

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 15y ago
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...

ScottSauyet 15y ago

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.