Commits

catseye  committed d197ed5

Pluralize file name, for consistency.

  • Participants
  • Parent commits 92c0986

Comments (0)

Files changed (2)

File data/language-construct.yaml

-# encoding: UTF-8
-# this one's a real grab-bag, for now
-Comment:
-  type: Language Construct
-  description: |
-    A comment is a part of a program that isn't part of the program.
-  commentary: |
-    Don't comment *who* or *when*. That's the source control system's job.
-    
-    Don't comment *what*. If I'm a programmer worth my salt, I can read your
-    code and figure out the *what*.
-    
-    Don't spend a lot of space commenting *how*. Just provide a reference,
-    like "Implements topological sort (see CLR)". If I'm an engineer worth
-    my salt, I can look it up if I'm not already familiar with it. If I
-    can't obtain the source, I can spend an hour or two studying the code,
-    and I'll probably pick up the gist of the *how*.
-    
-    PLEASE PLEASE PLEASE ALWAYS COMMENT *WHY*. No matter how good I am, no
-    amount of time I spend looking at your code will tell me what the hell
-    the reason for its existence is. I can only guess the *why*.
-    
-    Lastly, commenting *where* is optional, but can be quite entertaining.
-
-Exception:
-  type: Language Construct
-  description: |
-    An exception is a value which can be "thrown" or "raised" at some point in the
-    execution of a program. This act can be detected, and the exception
-    "caught", by an exception handler installed at some previous point in the
-    execution. Catching an exception causes execution to continue inside the
-    handler, which can then decide what to do next. An uncaught exception
-    generally causes the program to terminate.
-  commentary: |
-    Here is [[Cat's Eye Technologies]]' official position on exceptions:
-    
-    **Ask not where it makes sense to throw exceptions; ask where it makes
-    sense to *catch* them.**
-    
-    If exceptions denote truly *exceptional* events, then by definition, you
-    are not really *prepared* for them. You have to ask what your program
-    can possibly do to recover from them. Out of memory? Syntax error in the
-    configuration file? Database server down? Method doesn't exist? There's
-    probably nothing that your program *can* do about these things, aside
-    from giving up and notifying the person in charge that a problem has
-    occurred.
-    
-    In this view, the main reason to use an exception, rather than, say,
-    blithely dereferencing `NULL` and dumping core, is not because it is
-    really a better solution per se; it's just that it's *prettier*.
-    
-    Not that that's bad, especially for commercial software! A newspaper
-    article about a train wreck is a lot easier to handle psychologically
-    than having it happen in your back yard. But my point is,
-    [[Software Engineering|software-engineering]]-wise, the exception isn't really a
-    *solution* to anything. (And, for internal tools, you probably actually
-    *do* want to be at the scene of the train wreck — you'll need as many
-    grisly details as possible in order to diagnose the problem.)
-    
-    An approach that takes this to the extreme is
-    [[Erlang]]'s "let it crash" philosophy. Exceptions
-    are often touted as a way to avoid having a bunch of "error-return
-    checks" in your code. But if the problem is essemtially irrecoverable,
-    there's no sense having *any* error-return checks, even ones that are
-    dressed up as exception handlers. They'll just lead to a bunch of
-    seldom-taken code paths executing in hard-to-reason-about error-mode
-    states which run the risk of corrupting data (by e.g. inserting invalid
-    rows into a database.) Better by far to simply "let it crash" — log the
-    error and the condition that led to it, and abort the program. If the
-    program provides some kind of service, it can be restarted in a known
-    state by an external monitor program.
-    
-    If, on the other hand, the event isn't truly exceptional, then the
-    question to ask is "why is it being modelled as an exception?" Joel
-    Spolsky raises [some excellent points in regards to this
-    issue](http://www.joelonsoftware.com/items/2003/10/13.html) — multiple
-    return values are often a more coherent way to cast the flow of control.
-    The unique utility of exceptions is that they can perform non-local
-    returns — control need not return to the immediate caller, it can skip
-    back up to a procedure that called the procedure that called the
-    procedure that called this one, if that's where the handler was
-    installed.
-    
-    We believe that this property of exceptions should be taken into
-    consideration when deciding upon an exception strategy: Will the callers
-    of my caller ever care about this exception? When will the direct caller
-    of my code *not* want to catch it? What benefit does this exception
-    really have over an error-valued return value?
-    
-    [[Python]], for example, throws exceptions at the drop of a hat — when a
-    value is not found while searching a list, for example. But likely it
-    makes sense to catch that exception *always*, because *if you're
-    searching for something, it probably means it might not be there*. And
-    it makes sense to catch the exception *immediately after searching the
-    list*, because *your callers probably shouldn't care that you're
-    searching a list*. (If, in the future, you changed the implementation of
-    your function so that it looked things up in a dictionary instead, a
-    *different* exception would be thrown. Oi!)
-    
-    We feel that this is an injudicious use of exceptions, and that Python
-    is, sadly, hardly a unique language design in this regard.
-
-Closure:
-  type: Language Construct
-  description: |
-    In [[Programming Language|programming languages]], a closure is an abstraction
-    of an *expression* in an *environment*; the expression may contain *free
-    variables* which are given meaning by the values *bound* to them in the
-    environment.
-    
-    The programmer can generally treat a closure as they would any other
-    value: they can store it in a variable, pass it as an argument to a
-    function, and return it as the return value of a function. Language
-    constructs with this property are sometimes referred to as
-    "first-class."
-    
-    The closure is almost always a *function value* which can be called as
-    if it were it were any other function or procedure. (Function values are
-    also called *lambda functions* after an analogous construct, the
-    *abstraction*, in Church's *lambda calculus*.) However, closures over
-    other data types, for example entire modules, are possible.
-    
-    A closure is different from a "function pointer" you might find in a
-    language like C, because a closure has access to variables in the
-    environment associated with it. This environment is usually the set of
-    all variables that are "in scope" at the point in the program where the
-    closure is created.
-    
-    Since the environment of a closure may contain variables local to the
-    function in which it is created, and since the closure may be returned
-    as a value from that function, it may *outlive* the local variables
-    referred to by its environment. For this reason, the language (and by
-    extension its implementation) must ensure that those values continue to
-    exist for as long as the closure itself exists, for example by
-    allocating them on the heap instead of on the call stack.
-    
-    This is where the term "closure" comes from: it "closes over" the
-    variables in its environment. Note, though, that this use of the word
-    "closure" has no relationship to the mathematical notion of closure
-    (which basically means to keep doing something over and over until there
-    is nothing more that will change.)
-    
-    Closures seem to be one of those things that programming language
-    designs and/or implementations have trouble with:
-    
-    -   LISP was the first language to promote functions as values, but it
-        represented functions as lists and used dynamic binding to associate
-        values with variables. This was a mess, and it took a long time for
-        it to get better. Nowadays, [[Scheme]] has proper
-        closures, and is a much more attractive choice overall.
-    -   [[Javascript]] has closures, but they're notorious for
-        [leaking](http://www.jibbering.com/faq/faq_notes/closures.html#clMem).
-        Partly this is a consequence of the difficulty of interpreting the
-        definitions of the DOM — what should and what shouldn't stick around
-        for how long — but it is also due to the inadequacy of some vendors'
-        garbage collection implementations.
-    -   As of this writing, Python's closures are limited to a single
-        expression. This may be a syntactic problem rather than a semantic
-        one, but it is still something of an annoyance.
-    -   By overloading the `()` operator, it's possible to make closure-like
-        objects even in [[C++]]. But if you try this, you'll
-        soon appreciate why, in most languages, closures are garbage
-        collected: if you have to explicitly reason about when the free
-        variables will no longer be needed, you're not much better off from
-        using function pointers.
-    -   [[Java]], on the other hand, does have garbage collection, but doesn't
-        have closures; instead, what you get to do is to create an instance
-        of an anonymous class with a single method on it and initialize the
-        member variables of that class with the values you want that method
-        to close over. What fun!

File data/language-constructs.yaml

+# encoding: UTF-8
+# this one's a real grab-bag, for now
+Comment:
+  type: Language Construct
+  description: |
+    A comment is a part of a program that isn't part of the program.
+  commentary: |
+    Don't comment *who* or *when*. That's the source control system's job.
+    
+    Don't comment *what*. If I'm a programmer worth my salt, I can read your
+    code and figure out the *what*.
+    
+    Don't spend a lot of space commenting *how*. Just provide a reference,
+    like "Implements topological sort (see CLR)". If I'm an engineer worth
+    my salt, I can look it up if I'm not already familiar with it. If I
+    can't obtain the source, I can spend an hour or two studying the code,
+    and I'll probably pick up the gist of the *how*.
+    
+    PLEASE PLEASE PLEASE ALWAYS COMMENT *WHY*. No matter how good I am, no
+    amount of time I spend looking at your code will tell me what the hell
+    the reason for its existence is. I can only guess the *why*.
+    
+    Lastly, commenting *where* is optional, but can be quite entertaining.
+
+Exception:
+  type: Language Construct
+  description: |
+    An exception is a value which can be "thrown" or "raised" at some point in the
+    execution of a program. This act can be detected, and the exception
+    "caught", by an exception handler installed at some previous point in the
+    execution. Catching an exception causes execution to continue inside the
+    handler, which can then decide what to do next. An uncaught exception
+    generally causes the program to terminate.
+  commentary: |
+    Here is [[Cat's Eye Technologies]]' official position on exceptions:
+    
+    **Ask not where it makes sense to throw exceptions; ask where it makes
+    sense to *catch* them.**
+    
+    If exceptions denote truly *exceptional* events, then by definition, you
+    are not really *prepared* for them. You have to ask what your program
+    can possibly do to recover from them. Out of memory? Syntax error in the
+    configuration file? Database server down? Method doesn't exist? There's
+    probably nothing that your program *can* do about these things, aside
+    from giving up and notifying the person in charge that a problem has
+    occurred.
+    
+    In this view, the main reason to use an exception, rather than, say,
+    blithely dereferencing `NULL` and dumping core, is not because it is
+    really a better solution per se; it's just that it's *prettier*.
+    
+    Not that that's bad, especially for commercial software! A newspaper
+    article about a train wreck is a lot easier to handle psychologically
+    than having it happen in your back yard. But my point is,
+    [[Software Engineering|software-engineering]]-wise, the exception isn't really a
+    *solution* to anything. (And, for internal tools, you probably actually
+    *do* want to be at the scene of the train wreck — you'll need as many
+    grisly details as possible in order to diagnose the problem.)
+    
+    An approach that takes this to the extreme is
+    [[Erlang]]'s "let it crash" philosophy. Exceptions
+    are often touted as a way to avoid having a bunch of "error-return
+    checks" in your code. But if the problem is essemtially irrecoverable,
+    there's no sense having *any* error-return checks, even ones that are
+    dressed up as exception handlers. They'll just lead to a bunch of
+    seldom-taken code paths executing in hard-to-reason-about error-mode
+    states which run the risk of corrupting data (by e.g. inserting invalid
+    rows into a database.) Better by far to simply "let it crash" — log the
+    error and the condition that led to it, and abort the program. If the
+    program provides some kind of service, it can be restarted in a known
+    state by an external monitor program.
+    
+    If, on the other hand, the event isn't truly exceptional, then the
+    question to ask is "why is it being modelled as an exception?" Joel
+    Spolsky raises [some excellent points in regards to this
+    issue](http://www.joelonsoftware.com/items/2003/10/13.html) — multiple
+    return values are often a more coherent way to cast the flow of control.
+    The unique utility of exceptions is that they can perform non-local
+    returns — control need not return to the immediate caller, it can skip
+    back up to a procedure that called the procedure that called the
+    procedure that called this one, if that's where the handler was
+    installed.
+    
+    We believe that this property of exceptions should be taken into
+    consideration when deciding upon an exception strategy: Will the callers
+    of my caller ever care about this exception? When will the direct caller
+    of my code *not* want to catch it? What benefit does this exception
+    really have over an error-valued return value?
+    
+    [[Python]], for example, throws exceptions at the drop of a hat — when a
+    value is not found while searching a list, for example. But likely it
+    makes sense to catch that exception *always*, because *if you're
+    searching for something, it probably means it might not be there*. And
+    it makes sense to catch the exception *immediately after searching the
+    list*, because *your callers probably shouldn't care that you're
+    searching a list*. (If, in the future, you changed the implementation of
+    your function so that it looked things up in a dictionary instead, a
+    *different* exception would be thrown. Oi!)
+    
+    We feel that this is an injudicious use of exceptions, and that Python
+    is, sadly, hardly a unique language design in this regard.
+
+Closure:
+  type: Language Construct
+  description: |
+    In [[Programming Language|programming languages]], a closure is an abstraction
+    of an *expression* in an *environment*; the expression may contain *free
+    variables* which are given meaning by the values *bound* to them in the
+    environment.
+    
+    The programmer can generally treat a closure as they would any other
+    value: they can store it in a variable, pass it as an argument to a
+    function, and return it as the return value of a function. Language
+    constructs with this property are sometimes referred to as
+    "first-class."
+    
+    The closure is almost always a *function value* which can be called as
+    if it were it were any other function or procedure. (Function values are
+    also called *lambda functions* after an analogous construct, the
+    *abstraction*, in Church's *lambda calculus*.) However, closures over
+    other data types, for example entire modules, are possible.
+    
+    A closure is different from a "function pointer" you might find in a
+    language like C, because a closure has access to variables in the
+    environment associated with it. This environment is usually the set of
+    all variables that are "in scope" at the point in the program where the
+    closure is created.
+    
+    Since the environment of a closure may contain variables local to the
+    function in which it is created, and since the closure may be returned
+    as a value from that function, it may *outlive* the local variables
+    referred to by its environment. For this reason, the language (and by
+    extension its implementation) must ensure that those values continue to
+    exist for as long as the closure itself exists, for example by
+    allocating them on the heap instead of on the call stack.
+    
+    This is where the term "closure" comes from: it "closes over" the
+    variables in its environment. Note, though, that this use of the word
+    "closure" has no relationship to the mathematical notion of closure
+    (which basically means to keep doing something over and over until there
+    is nothing more that will change.)
+    
+    Closures seem to be one of those things that programming language
+    designs and/or implementations have trouble with:
+    
+    -   LISP was the first language to promote functions as values, but it
+        represented functions as lists and used dynamic binding to associate
+        values with variables. This was a mess, and it took a long time for
+        it to get better. Nowadays, [[Scheme]] has proper
+        closures, and is a much more attractive choice overall.
+    -   [[Javascript]] has closures, but they're notorious for
+        [leaking](http://www.jibbering.com/faq/faq_notes/closures.html#clMem).
+        Partly this is a consequence of the difficulty of interpreting the
+        definitions of the DOM — what should and what shouldn't stick around
+        for how long — but it is also due to the inadequacy of some vendors'
+        garbage collection implementations.
+    -   As of this writing, Python's closures are limited to a single
+        expression. This may be a syntactic problem rather than a semantic
+        one, but it is still something of an annoyance.
+    -   By overloading the `()` operator, it's possible to make closure-like
+        objects even in [[C++]]. But if you try this, you'll
+        soon appreciate why, in most languages, closures are garbage
+        collected: if you have to explicitly reason about when the free
+        variables will no longer be needed, you're not much better off from
+        using function pointers.
+    -   [[Java]], on the other hand, does have garbage collection, but doesn't
+        have closures; instead, what you get to do is to create an instance
+        of an anonymous class with a single method on it and initialize the
+        member variables of that class with the values you want that method
+        to close over. What fun!