Subtitle: when CoffeeScript rock stars run around naked in public

Just because you can do something doesn’t mean you should. Leaving the parentheses out of your CoffeeScript might make your code look a bit more “natural”, but it almost always makes the code less readable and in a many cases, it makes it impossible for the CoffeeScript compiler to understand your intent. It’s more “natural” to go around naked but you shouldn’t. Just like you need to cover your private parts when you go outside, you should properly cloth your CoffeeScript function/method parameters in parentheses.

I know… you want to show that you are a CoffeeScript cool-kid. You can write a one-line list comprehension that is like a brilliant guitar solo. But I think it’s cooler for my code to be readable and for the compiler to precisely understand what I intend. The list comprehension guitar solo may be showing off but we expect our cool rock stars to show off. However, it’s uncool (even for rock stars) to be drug-addled running around naked in public. Be the rock star without the drugs… or running around without your function/method calls properly clothed in parentheses.

In the last few months alone, on StackOverflow, there have a been at least six questions that I have flagged as caused by this issue:

• Chaining
• Calling functions with no parameters
• Lambdas with multiple functions
• Help showing code flow with jquery
• Calling a function which calls a function
• Confusing space

In all of the cases above, there is an idiom that you can’t precisely/clearly express without parentheses around function/method parameters. Often, the coder realizes that it’s ambiguous but “hopes” that the compiler can figure out his intent. He posts a question on StackOverflow once he is able to show that it cannot. In all of these cases, the coder has learned CoffeeScript by looking at a bunch of examples that leave out the parentheses and he doesn’t realize that you can put them in… or he wants to know how the cool-kids express it without them. In each case, the answer is invariably, “Simply add parentheses and it will work as expected.”

If this is confusing the compiler and the new users who want to be CoffeeScript cool-kids, we CoffeeScript bloggers should all make an effort to post all examples with the parentheses left in. I’m going so far as to leave them in all of my code and my collaborators seem to appreciate it. If nobody ever needs to read your code, then feel free to walk around naked in a drug-addled state within the privacy of your own home. But as soon as you step out the door, or want anyone else to read your code…

It’s perfectly fine to leave them out of if-statements, while-loop, etc. We like our female rock starts to show a little cleavage and some folks get turned on by Mick Jagger’s tight leather pants.

Chaining (needed for compiler to understand intent)

someObject.slideLeft(4).invert().slideUp(10)

Calling a parameter-less method (also necessary)

someIterator.next()

Function/method calling (even when not chaining, for human clarity)

someFunction(parameterA, parameterB)

…Even when the last parameter is a callback (Yeah, I know, the CoffeeScript cool-kids think this is ugly and a pain to line up the ending parentheses but it’s worth it for the clarity gain, IMHO. Suck it up rock star, even Bob Dylan had to adjust his lyrics so his listeners could understand him… well, maybe Bob Dylan could get away with confusing shit. But face it, you are NOT as cool as Bob Dylan… and coding requires a precision that isn’t needed in poetry/music. )

someMethodNeedingACallback(parameterA, (err, data) -> console.log(data) )

Functions with no parameters (could live without this, but IMHO, it’s more readable with it)

f = () -> return "hello" # notice how I also like to say "return". That's another clarity choice.

One last argument to try to convince you… Python is the most readable programming language out there. The Python BDFL has come out time and again in favor of readability even at the expense of conciseness. Python used to have a parentheses-less print statement, but Guido feels so strongly that this was a mistake, that he went through the very painful backward-breaking change to require parentheses for print function calls in Python 3.0. I would go so far as to argue that we should remove this “feature” from the CoffeeScript spec but even if we don’t, we should stop using it.

The examples you add to document your project are like a map to the buried treasure that is your library/API/tool/etc. But if the examples are wrong, it’s like labeling the map with “promised land” right over the spot where it should say, “there be dragons”.

It’s less about testing your code with your documentation, than the other way around. Make sure that the examples in your documenation stay current with your code. coffeedoctest is a way to test your documentation with your code… to make sure that the map matches the terrain.

If you’ve spent any time working in Python, then you are probably familiar with doctest. Coffeedoctest is built along the same lines.

For entire story visit the coffeedoctest project page on github.

I’ve been doing more coding in CoffeeScript and as any good craftsman knows, you must sharpen the saw from time to time. This time, I added some convenience commands for doing line manipulation by writing my very own Panic! Coda plugin.It will allow you to delete, duplicate, and move lines with a keystroke. There is also a convenience shortcut for wrapping a variable in console.log.

It was actually pretty easy using Panic!’s Coda Plug-in Creator. I wrote my text manipulation code in javascript as shell scripts that would run under node.js and simply dragged them into the Coda Plug-in Creator.

You can find it on GitHub here.

I recently started rewriting all of my PhD tools in CoffeeScript from ActionScript. I’m loving the python-like syntax and I’m very happy with the language as well as the ecosystem around CoffeeScript and node.js. Tools are an important part of the experience so I’ve played around with several editors/IDE’s for writing CoffeeScript. Here is a quick comparison.

Coda

This is probably my favorite environment right now. I’m using a custom CoffeeScript.mode that I forked from Sean Durham to add navigator support.

Pros:

• Nice clean interface written for the Mac
• Syntax highlighting that works in both .coffee and CakeFile
• Instant startup/shutdown and low resource usage. I can code on battery for 4+ hours on my MacBook Pro.
• Preview mode for HTML.
• Hackable. I already upgraded the 3rd party mode file. I have thoughts on plugins for running unit tests and reporting code coverage.

Cons:

• Only subversion integration. Personally, I never use the source code integration built into editors and IDE’s so this is not a problem for me. But EVERYONE uses git for CoffeeScript. I just started using GitHub for Mac. I’ll see how that goes but I can always use the command line.
• No code folding. Again, not a feature that I miss too much because I can put each class into a different file. The navigator is also a decent substitute.

WebStorm

Pros:

• Refactoring.
• NodeUnit support built in. Nice!!!
• Keystrokes that make sense to me. Ctrl-Y means yank this line. It’s the only one of the three that does that.

Cons:

• Still beta quality
• The syntax highlighter doesn’t like multi-line comments “###”…”###” to have any “#” inside. Until they fix this, I’m not going to use it again.
• My .idea folder got corrupted several times and each time it lost my configuration foo for running nodeunit tests.
• Heavyweight. It’s essentially the IntelliJ IDE with java editing (and a bunch of other functionality) removed.

TextMate

I started writing CoffeeScript in TextMate and I still pull up .coffee files for a quick look in TextMate so this is my backup.

Pros:

• Syntax highlighting that works. I think TextMate’s is the basis for the Coda one that I use.
• Folder as a project. I like this concept and you can sorta do this in Coda but it’s nice to open one project/folder with tabs for all of the files that are part of that project but still be able to open separate windows for other files that I randomly need to edit. If you right-click…open in Coda, it’ll create another tab in the “workspace” that you are working in even if the file has nothing to do with that project.

Cons:

• None really other than it missing some of the Pros of Coda.

The URLMultiLoader class in this library will load multiple files and optionally “process” them before calling the method specified for Event.COMPLETE. Since file loading in the Flash/Flex/AS3 world is completely asynchronous, when you need to load more than one file, the hackish solution is to make the COMPLETE handler for the first one initiate the load for the second, etc. until all the files are loaded. URLMultiLoader will allow you to setup one COMPLETE handler which will not be called until all the files you specify are loaded (and optionally “processed”).

When I first had need for this, I said to myself that someone must have done this before. It seems like a fairly common need. However, when I went looking, I couldn’t find something that fit the bill, so I decided to write my own. It was actually a very good way to get familiar with the event system. Also, while I was at it, I figured I’d allow the injection of a processor for each file and make sure that got processed before proceeding. If anyone knows of another tool like this please post a link to it in the comments. Actually, it wouldn’t surprise me if this functionality is built into the Flex framework somewhere and I just missed it.

Update: The functionality mustn’t be in Flex because I have now found several other similar controls:

• BulkLoader
• QueueLoader
• UltimateLoader

Mine is relatively simple compared to some of these. BulkLoader seems particularly featureful. It has bandwidth stats and progress indicators. For my loading needs, the sizes were small enough that I wasn’t worried about progress or bandwidth, but I may update mine to include these features in the future.

One feature that mine has that many do not have is the optional ability to inject in a an IDataProcessor that will pre-process your data before returning it to you.

DataProcessorXMLStringToArray is provided as an example IDataProcessor that can optionally be passed in when adding a new URLRequest to the queue. If provided, an IDataProcessor will convert the raw file string (or binary, or url variables) into some other form before returning. Complete documentation for DataProcessorXMLStringToArray is provided in the ASDoc header for the class but it is offered here primarily as an example. You can easily create your own and inject them when setting up the URLMultiLoader. You just need to follow the IDataProcessor interface which has one method with the following signature:

function processData(data:*):*

Remember, the processor is totally optional. If omitted, URLMultiLoader will simply copy the file contents into it’s output data field. The type of the data in that case will depend upon the URLLoaderDataFormat: String for TEXT (default), ByteArray for BINARY, and URLVariables for VARIABLES.

Let’s see it in action.

package
{
	import com.maccherone.urlmultiloader.*;
	import com.maccherone.json.JSON;  // Only used for pretty output
 
	import flash.display.Bitmap;
	import flash.display.Loader;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.events.IOErrorEvent;
	import flash.net.URLLoaderDataFormat;
	import flash.net.URLRequest;
 
	public class URLMultiLoaderTest extends Sprite
	{
		private var urlMultiLoader:URLMultiLoader = new URLMultiLoader()
		private var baseURL:String = "data/"
		private var urlRequest1:URLRequest = new URLRequest(baseURL + "file.xml")
		private var urlRequest2:URLRequest = new URLRequest(baseURL + "file.xml")  // Same file but we'll get it in a different format
		private var urlRequest3:URLRequest = new URLRequest(baseURL + "smile.gif")
 
		public function URLMultiLoaderTest() {
			var urlMultiLoader:URLMultiLoader = new URLMultiLoader
 
			var dataProcessor:IDataProcessor = new DataProcessorXMLStringToArray()  // Example provided with URLMultiLoader. You can create your own.
 
			urlMultiLoader.addURLRequest("Request1", urlRequest1, dataProcessor)
			urlMultiLoader.addURLRequest("Request2", urlRequest2)  // If no IDataProcessor is provided, then file's contents is returned as String, ByteArray, or
			                                           // URLVariables depending upon the URLLoaderDataFormat TEXT, BINARY, or VARIABLES respectively
			urlMultiLoader.addURLRequest("Request3", urlRequest3, null, URLLoaderDataFormat.BINARY)  // Loads smile.gif as a ByteArray
 
			urlMultiLoader.addEventListener(Event.COMPLETE, filesLoaded)
			urlMultiLoader.addEventListener(IOErrorEvent.IO_ERROR, onError)
			urlMultiLoader.load()
		}
 
		private function filesLoaded(event:Event):void {
			var data:Object = (event.target as URLMultiLoader).data
			trace("Array of Objects:\n" + JSON.encode(data["Request1"], true) + "\n") // Uses JSON.encode for pretty output
			trace("String of file contents:\n" + data["Request2"] + "\n")
			var loader:Loader = new Loader();
			loader.loadBytes(data["Request3"]);
			this.addChild(loader)  // Displays smile.gif in Flash player
		}
 
		private function onError(event:Event):void {
			trace(event)
		}
	}
}

Assuming you put the file.xml and the smile.gif , in a data/ folder below the bin-debug directory and you have the correct security settings, the above code would result in the following output:

Array of Objects:
[
    {"id": 101, "name": "/db/node/visitor"},
    {"id": 102, "name": "/db/node/observer"},
    {"id": 103, "name": "/ui/button"}
]
 
String of file contents:
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <file>
    <id>101</id>
    <name>/db/node/visitor</name>
  </file>
  <file>
    <id>102</id>
    <name>/db/node/observer</name>
  </file>
  <file>
    <id>103</id>
    <name>/ui/button</name>
  </file>
</root>

Plus it will display smile.gif in the Flash player like this:

You can download it from here.

Update: I altered the URLMultiLoader to use a string as the key to retrieving the data after the loading is complete. A previous version used the URLRequest as the key for Dictionary object. This version does not depend upon Dictionary.

I’m sure many ActionScript 3 or Flex developers have used the as3corelib for one reason or another. It’s a wonderful little library with lots of useful functionality. I’ve frequently used its JSON  encoding and decoding functionality. It works great, however, it doesn’t add spaces or linefeeds to make the resulting JSON string more readable. That’s fine if you are just serializing something to send over the wire but not if you want it to render something that is easily read by a human. In my case, I want a user to actually be able to edit the resulting JSON. To make this workable, I needed a JSON encoder that would add appropriate linefeeds and spaces. Rather than write my own, I simply adapted the one in as3corelib.

One side benefit of having done this is that you can now get JSON serialization without getting the entire as3corelib library.

The default interface is identical to the one in as3corelib. If you just call JSON.encode(my_object), it will behave almost exactly like the one in as3corelib. I say “almost” because my version add a space after each “:” and “,” even in default mode. Update: I’ve changed it so it behaves exactly like the serializer in as3corelib so no extra spaces are added unless you use the optional parameters described below.

If you want linefeeds and truly “pretty” output, you can add an optional second parameter, like so JSON.encode(my_object, true). This will cause any array [ ] or object { } that would be longer than 60 characters to wrap to newlines, which works out about right for my purposes.

You can also adjust the maximum line length with an optional third parameter, like this JSON.encode(my_object, true, 10). This will cause any line above 10 to wrap. If you want every array [ ] and object { } to wrap, just use any number 2 or lower in this third parameter. If you want it to wrap everything but empty objects or arrays, use 3 for this parameter.

Let’s see it in action.

package
{
    import com.maccherone.json.JSON;
    import flash.display.Sprite;    
 
    public class Tester extends Sprite
    {
 
        public function Tester()
        {
            var obj1:Object = {
                commit: {file: "commit.xml"},
                commit_detail: {file: "commit_detail.xml"},
                file: {file: "file.xml"},
                person: {file: "person.xml"},
                count: [1, 2, 3]
            }
            trace("Just like as3corelib (no line feeds or spaces):\n" + JSON.encode(obj1) + "\n");
            trace('"Smart" linefeeds:\n' + JSON.encode(obj1, true) + "\n");
            trace("Only allow short lines:\n" + JSON.encode(obj1, true, 10) + "\n");
 
            var obj2:Object = {
                "glossary": {
                    "title": "example glossary",
                    "GlossDiv": {
                        "title": "S",
                        "GlossList": {
                            "GlossEntry": {
                                "ID": "SGML",
                                "SortAs": "SGML",
                                "GlossTerm": "Standard Generalized Markup Language",
                                "Acronym": "SGML",
                                "Abbrev": "ISO 8879:1986",
                                "GlossDef": {
                                    "para": "A meta-markup language, used to create markup languages such as DocBook.",
                                    "GlossSeeAlso": ["GML", "XML"]
                                },
                                "GlossSee": "markup"
                            }
                        }
                    }
                }
            }
            trace("A bigger example from JSON.org:\n" + JSON.encode(obj2, true));
        }
    }
}

The above code would result in the following output:

Just like as3corelib (no line feeds or spaces):
{"file":{"file":"file.xml"},"commit":{"file":"commit.xml"},"commit_detail":{"file":"commit_detail.xml"},"person":{"file":"person.xml"},"count":[1,2,3]}
 
"Smart" linefeeds:
{
    "file": {"file": "file.xml"},
    "commit": {"file": "commit.xml"},
    "commit_detail": {"file": "commit_detail.xml"},
    "person": {"file": "person.xml"},
    "count": [1, 2, 3]
}
 
Only allow short lines:
{
    "file": {
        "file": "file.xml"
    },
    "commit": {
        "file": "commit.xml"
    },
    "commit_detail": {
        "file": "commit_detail.xml"
    },
    "person": {
        "file": "person.xml"
    },
    "count": [1, 2, 3]
}
 
A bigger example from JSON.org:
{
    "glossary": {
        "GlossDiv": {
            "GlossList": {
                "GlossEntry": {
                    "GlossSee": "markup",
                    "GlossTerm": "Standard Generalized Markup Language",
                    "ID": "SGML",
                    "GlossDef": {
                        "para": "A meta-markup language, used to create markup languages such as DocBook.",
                        "GlossSeeAlso": ["GML", "XML"]
                    },
                    "Abbrev": "ISO 8879:1986",
                    "Acronym": "SGML",
                    "SortAs": "SGML"
                }
            },
            "title": "S"
        },
        "title": "example glossary"
    }
}

Note that (unlike XML) the order of the elements in a JSON object { } is indeterminant. Of course the order of an array [ ] is preserved.

You can download it from here.