Home » forums » LtU Forum

How to explain a new programming language?

I'm revising a paper and have gotten stuck on a very hard problem: how do you describe a completely new programming language in 3 pages to an audience that might not want to care very much (the language is a detail rather than the core contribution). My current style of writing feels like an example dump: describe feature X, describe example that uses feature X, wash rinse and repeat with feature Y.

Or perhaps the question should be: what do readers care about when reading a PL? What details will satisfy them and what details can be left out without angering them or making them feel deceived?

By Sean McDirmid at 2011-06-28 03:07 | LtU Forum | previous forum topic | next forum topic | other blogs | 8210 reads

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

All readers aren't alike

I myself enjoy "tasting" programming languages (as also natural languages), so what I want to see is the reference manual/grammar, though I may not end up reading every word of it.

By johnwcowan at Tue, 2011-06-28 04:20 | login or register to post comments

depends a lot on the details

You need to accomplish three things. 1) convince the reader they already understand much/most of your language. 2) introduce them to the novel aspects of your language that are relevant to your paper. 3) get them to suspend their disbelief that you actually need a new language.

I'm guessing your language has a novel approach to something and that is the subject of the paper. Your presentation of the language is more about building up a conceptual map of your subject and situating your contribution than it is about teaching your audience the language. They don't need to be able to program in it, only understand your examples.

By Robb Nebbe at Tue, 2011-06-28 13:14 | login or register to post comments

Great answer

I was about to give roughly the same answer myself so virtual mod +1.

By JeffB at Tue, 2011-06-28 18:35 | login or register to post comments

The tricky part is getting

I have something like that right now..the section begins like...

YinYang is a graphical language whose design supports tablet-based program construction with two core features. First, control flow is based on Brooks’ subsumption architecture [1] where overall object behavior emerges from multiple arbitrated simpler behaviors. Second, one tile construct can abstract both verbal “doing” and nounal “being” logic, and is a type when checking that abstractions are used meaningfully. These features simplify YinYang’s syntax and reduce the amount of code needed to express programs. The rest of this section informally describes how to understand YinYang code; we discuss the code editing experience in Section 3 and semantics and implementation in Section 4

...before going into example territory. But one claim made in the paper is one of capability, that the language is scalable enough to encode real programs (vs. end-user programming environments). I then get trapped into proving that capability.

By Sean McDirmid at Wed, 2011-06-29 00:17 | login or register to post comments

Know your audience, and iterate

I had great difficulty with this issue when preparing my SIGGRAPH 2011 paper. My audience consisted of graphics experts rather than PL theorists, and my first few drafts were rightly criticized by my colleagues for reading too much like a reference manual.

My best advice is to focus on the contribution for this particular paper, and don't be afraid to cut any details that aren't required to explain that contribution. Your readers don't have to come away knowing how to program in your language, they just need to know why you designed it, and what you learned in doing so. For myself, I posed the question: "If somebody in industry wanted to use my research in building a new system/language, what are the most important warnings and pieces of advice I'd give them, based on my experience?"

For non-PLT readers (and even most PLT readers, I suspect) a few carefully chosen examples will be far more persuasive than detailed and precise definitions. If you can walk through one non-trivial code example and leave your readers with the sense that they understand it in spirit (though not in detail) you are probably doing well.

By Tess Foley at Tue, 2011-06-28 14:51 | login or register to post comments

My readers are the opposite:

My readers are the opposite: convincing PL people of an HCI-like contribution. They won't let me handwave as much as I'd like on language details. The paper is a conditional accept, so I have the review comments already...conditional b/c I was too imprecise in my description of the PL, I think.

By Sean McDirmid at Tue, 2011-06-28 23:05 | login or register to post comments

Compare to existing languages...

For example...

Java has a C/C++ like syntax, a C++ like hydrid POD/Object model not a pure one object model like Ruby or smalltalk.

The private/protect/public notions of Java are confusingly different to C++.

It is Garbage collected with finalisers.

It has native support of multithreading (syncronise and volatile) ....
... so on and so forth.

After their are very few features in the world of PLD that don't already exist in some language or other.

By John Carter at Tue, 2011-06-28 22:42 | login or register to post comments

After their are very few

After their are very few features in the world of PLD that don't already exist in some language or other.

The language is graphical and has a very weird control-flow model when compared to the existing languages. The only language I can really compare to directly is its inspirational ancestor, Kodu, but Kodu is not widely enough known for the comparison to be useful in explaining things.

By Sean McDirmid at Tue, 2011-06-28 23:10 | login or register to post comments

You may have mentioned it in the draft...

...or maybe in another LtU discussion about your work, but it seems like the mental model for your language is most closely related to Rodney Brooks' Subsumption Architecture. That link to robotics is probably not accidental, given that your system is about controlling logically autonomous agents.

It is definitely important to establish the underlying mental model for your language, especially if it differs from the typical approaches readers might be familiar with. At some level this needs to be the "elevator pitch" for your language, and if you haven't worked one of those out already, you probably should.

The advice I repeatedly got from my adviser was that if I couldn't explain something succinctly and clearly, it was probably a sign that I didn't understand it as well as I thought. I tend to bristle at an implication like that, but I certainly found that the work I did on explaining my ideas better tended to impact my own understanding of those ideas.

By Tess Foley at Wed, 2011-06-29 14:24 | login or register to post comments

I've always found that my

I've always found that my ideas become clearer via writing, so the act of writing a paper is my idea-polishing-process. Part of the major problem with the initial draft of the touch programming paper is that the idea wasn't clear enough, so my writing was confused. I think I'm addressing this as it seems to be a pure function of time and writing.

As the idea becomes clearer, what is the best style to explain the language? Take my last paper on live programming, which was clear (I guess) but Section 2 still seems like quite an example dump. Going back and looking at my previous papers, this seems to be my chosen "style" and I was wondering if the style is really appropriate, and if not, how could I go beyond it. Other papers seem to get away with way fewer examples and can be just as clear if not more clear.

By Sean McDirmid at Wed, 2011-06-29 23:05 | login or register to post comments

know your audience?

everybody reading will have a different best way to "get it". maybe you can at least think of a couple pedagogical styles, and put them in a couple sections of your paper, and tell people up front to read it in whatever order they choose?

By raould at Thu, 2011-06-30 22:27 | login or register to post comments

Why are you describing it?

I'm hoping you have a reason for describing this language to this audience. And a reason for having that reason, etc, until it gets back to something the audience directly cares about.

If the reason is that "the code examples in the paper are in this language", and the reason for that is "this language allows me to talk more directly about these ideas than I otherwise could," and the reason for that is "because this language's flow of control is based on the subsumption architecture" and the reason for that is "because this domain is closely modeled by the subsumption architecture" then:

You start out by explaining exactly how and why this problem domain is related to, paralleled by, or expressed best in the domain of the subsumption architecture. (Note! If this is a result unexpected by most, and you can rigorously explain your reasoning, then this in itself might be worth a paper!)

Then shift from the mathematical notation you'll need to express that to a programming language that neatly parallels the mathematical notation. If the paper is not *about* the programming language, then you don't need to explain the language in the body of the paper.

Instead you stick an appendix onto your paper that describes the language, and reference that appendix from the code examples.

By Ray Dillinger at Sat, 2011-07-02 17:16 | login or register to post comments

The paper includes how

The paper includes how language design influences interface design. The goal is tablet-based programming, we have to design a language and interface to get their, the design of the language is very key to making a viable interface possible.

I thought about going the language-light approach but I concluded it wouldn't work in this case. How do you claim that a type system feeds that appropriate amount of context into your UI without explaining the type system?

By Sean McDirmid at Sun, 2011-07-03 01:39 | login or register to post comments

First you have to explain why you need the context.

Before you can even claim that your type system feeds the appropriate amount of context into your UI, you have to explain to your audience why you need that amount of context (why the particular domain of tablet-based programming, if that's what your paper is about, demands it and why other programming domains do not) and why the type systems provided in existing languages do not deliver it.

In other words, you have to explain the need for the new type system and the inadequacy of the old type systems in terms of something your audience cares about (the subject of your paper) before an explanation of the new type system and specifically why it meets the need you've described will be seen as on-topic.

By Ray Dillinger at Thu, 2011-07-07 02:51 | login or register to post comments