update broken and outdated examples

[showell]

Edit: This thread started with a fairly narrow issue, then the discussion broadened to the state of the "examples" directory.
The proposal here is to fix two small problems in the computer_science directory (one of which Michael just fixed, thank you), and then to deprecate some examples that are probably not worth maintaining going forward.

Original post:

The linked_list.coffee example in examples/computer_sciences uses a bare constructor that is misleading:

The code below doesn't do it what it suggests, and, in fact, you can remove the code and the example still works.

->
  this._head = null # Pointer to the first item in the list.

[michaelficarra]

I think a lot of the /examples/* files are outdated.

[showell]

The examples in in beautiful_code and computer_science are still useful, and there are only two minor issues, both of which are easy to fix (see issue 1699 as well as this one).

The unclassified examples are less useful, except for underscore.coffee and web_server.coffee. I recommend removing blocks, code, poignant, and potion.

[showell]

The slightly deeper issue here is that the bare constructor syntax hasn't been properly deprecated. The code below compiles fine, but it doesn't do anything.

class Foo
  ->
    console.log "hello"

foo = new Foo()

[michaelficarra]

hasn't been properly deprecated

Not really. We allow top-level function literals, so we allow function literals in class bodies. Neither one of them do anything. Remember, they're supposed to be executable bodies, so code inside class blocks is just like the code outside, but with a different context. At least that's the way executable class bodies are supposed to work...

[michaelficarra]

changing the title of this issue to better reflect the goal

[showell]

How can you call something an executable body if it's never executed and there's no way to reach it?

CS:

class Foo
  -> console.log "hey"
foo = new Foo()

JS:

var Foo, foo;
Foo = (function() {
  function Foo() {}
  (function() {
    return console.log("hey");
  });
  return Foo;
})();
foo = new Foo();

The innermost function above never gets executed, nor is it ever bound to a variable. It's just completely dead code, unless I'm missing something very subtle.

[showell]

Michael, I'd like to open a new issue for "bare constructors lead only to dead code", but I don't want to lose your comments here. Please advise. (I think cleaning up the examples directory can be accomplished with less debate if we don't digress too much on more core issues, and I kind of started us down the wrong path.)

One option is to close out this issue and then start fresh on the two other issues. (You're the only other participant so far on this one.)

[showell]

Michael, I think I understand your point a little better. You can put a bare constructor back into a context where it executes just by adding "do". I still think it's pointless to generate the dead code when the unbound function is not prefaced by "do", and it's probably a good thing to warn about. Even when you add the "do", I think many users will be surprised by the value of this, but I think CS is technically correct here.

class Foo
  do ->
    console.log this
    @foo = "hello"
  bar: ->
    console.log @foo

foo = new Foo()
foo.bar() # prints undefined

[michaelficarra]

This bare function/object literal discussion has been moved to #1709, so if anyone wants to comment about it, post your comments there. This issue's topic from here on is updating the examples in the /examples directory.

[GeoffreyBooth]

I’m updating the documentation in preparation for the 2.0.0 release. Anyone watching this thread care to tell me what you’d like to keep or remove from /examples? I know, it’s been gnawing at you for five years, now is your chance!

[GeoffreyBooth]

Closed in #4367