Inform 7 game source is hard to read
Tim
sometimes? I was looking at "When in Rome 1" which for all its other
benefits has things laid out in such a way that not only is the code not
easier to read, but its actually more confusing to use as an example. One
example: the text "A person can be active or passive" is in the section
titled "Creature Actions." I wouldn't even think to look there. I'm not
picking on one game here so that's not my point. I'm just noticing that
unclear code is much easier to produce with Inform 7 than with just about
any language I've used.
Khelwood
I imagine that the indexing feature is supposed to make such things
easy to locate during writing.
Andrew Plotkin
> I'm just noticing that
> unclear code is much easier to produce with Inform 7 than with just about
> any language I've used.
This has not been my experience.
(Currently dealing with the hardest-to-read code I've ever been
professionally required to understand. It's Java.)
--Z
--
"And Aholibamah bare Jeush, and Jaalam, and Korah: these were the borogoves..."
*
If the Bush administration hasn't subjected you to searches without a
warrant, it's for one reason: they don't feel like it. Not because of
the Fourth Amendment.
Michael Martin
> Here, Tim <.> wrote:
> > I'm just noticing that
> > unclear code is much easier to produce with Inform 7 than with just about
> > any language I've used.
> (Currently dealing with the hardest-to-read code I've ever been
> professionally required to understand. It's Java.)
I think it's a tossup between Java and Perl for me, but I may be going
easier on Java because the code, while hard to read in the raw, was
tolerable with the help of Eclipse's code browsers. I think it's true
that Inform 7 works past a certain size are going to need heavy use of
the Index tabs to navigate sensibly, but, well, that's why the
compiler produces the indices with the code.
I know a fellow (who's not a programmer) who's been trying to get an
IF work off the ground for some time (first in I6, now in I7) who's
been having some trouble making sense of pre-written I7 code as well,
but I haven't yet talked with him enough yet to determine if this is
due to (a) the code he's reading being confusing, (b) him
misunderstanding some concept that's blocking understanding, or (c)
him having unrealistic expectations for comprehension levels on a code
readthrough.
When in Rome is probably a particularly bad example for casual
codereading because it's got absolutely enormous libraries that aren't
entirely used by any given episode, and so one is keeping track of a
huge amount of state that isn't necessarily going to be relevant to
understanding the game itself. And that's even before getting into
the fact that the core gimmick of WiR is a goal-directed AI that would
be extremely complex in any language.
To the original poster, for what it's worth, I found ROTA and Bronze
to be the most readable of the code examples; ROTA in particular is
organized so that a readthrough from beginning to end (mostly)
produces a coherent whole, in steadily increasing complexity. (The
only exception is the Maze of Royal Beasts, which appears before the
Old School despite being several orders of magnitude more complex.)
--Michael
Andrew Plotkin
> On Apr 2, 2:46 pm, Andrew Plotkin <erkyr...@eblong.com> wrote:
>
> > (Currently dealing with the hardest-to-read code I've ever been
> > professionally required to understand. It's Java.)
>
> I think it's a tossup between Java and Perl for me, but I may be going
> easier on Java because the code, while hard to read in the raw, was
> tolerable with the help of Eclipse's code browsers. I think it's true
> that Inform 7 works past a certain size are going to need heavy use of
> the Index tabs to navigate sensibly, but, well, that's why the
> compiler produces the indices with the code.
On the specific example of the original post (a property declaration
in an obscure spot)...
I7 gives you more freedom than most languages to reorder your
declarations. (I believe there are still ordering constraints, but not
many.)
However, I don't think this sets I7 very far apart from other
languages. In every language I've worked with, most of the actual code
you write -- as measured in lines of code -- can be reordered very
freely. That is: C requires you to declare a variable before you use
it. But you declare it in one spot, and use it in a hundred spots, so
only 1% of the ordering decisions are forced on you by the language.
Similarly, Java is really insistent that you group "related" variables
and methods together as a class. But it doesn't care at all how you
order those declarations within the class. And, in practice, classes
that do a lot of work become very large -- so there are lots and lots
of ordering decisions there.
The upshot of all this is that I7 requires you to think carefully
about your code arrangement in order to make it readable -- but this
is true of every other programming language too, as soon as you're
dealing with more than one page of code.
--Z
--
"And Aholibamah bare Jeush, and Jaalam, and Korah: these were the borogoves..."
*
It's a nice distinction to tell American soldiers (and Iraqis) to die in
Iraq for the sake of democracy (ignoring the question of whether it's
*working*) and then whine that "The Constitution is not a suicide pact."
Emily Short
> Anyone else noticed that Inform 7 game source is really hard to read
> sometimes? I was looking at "When in Rome 1" which for all its other
> benefits has things laid out in such a way that not only is the code not
> easier to read, but its actually more confusing to use as an example. One
> example: the text "A person can be active or passive" is in the section
> titled "Creature Actions."
It's not irrelevant (though possibly undercommented): the active/
passive state of a character is used to control whether it is free to
perform any more actions on a given turn, or whether it has already
acted/has been neutralized. I tend to organize code, where possible,
so that information pertaining to a given simulation system is all in
one place.
Anyway, I'll grant that these examples need a bit of an overhaul,
especially as I7's grammar has changed substantially (in the direction
of simplicity, much of the time) since I produced them. We mainly
included the WiR episodes to demonstrate what the chaining of NPC
actions can be used to produce fairly complex goal-seeking behavior,
in the context of a complete game. But I wouldn't recommend these at
all as the first I7 source code one studied. If you want to understand
their core ideas without having to work through nearly as much
material, all the same essential concepts are demonstrated in the
examples of the Advanced Actions chapter.
(And because I thought of these as "advanced" examples, I didn't spend
as much time adding comments as I did with the others.)
> I wouldn't even think to look there. I'm not
> picking on one game here so that's not my point. I'm just noticing that
> unclear code is much easier to produce with Inform 7 than with just about
> any language I've used.
That may still be, but the specific thing you're pointing out, at
least, is a case of I7 allowing me to lay out the code in the way that
I as author find most intuitive.
Adam Thornton
Andrew Plotkin <erky...@eblong.com> wrote:
>I7 gives you more freedom than most languages to reorder your
>declarations. (I believe there are still ordering constraints, but not
>many.)
Scene ordering declarations have just become tighter in 4S08. You can
guess how I found that out.
Adam
Daryl McCullough
>(Currently dealing with the hardest-to-read code I've ever been
>professionally required to understand. It's Java.)
Are you saying that Java is the hardest-to-read *language*,
or that the particular code samples that you're looking at
are hard to read?
--
Daryl McCullough
Ithaca, NY
steve....@gmail.com
organization is not the main problem.
It's nevertheless a more serious problem than Plotkin perhaps admits,
since it's really not only a question of distributing the declarations
in a way that they make sense well with each other -- which is of
course extremely important. It's also a matter of knowing, and knowing
that you know, where the boundaries are.
It's easier to understand the Thing class if you know that all
properties and methods of the class are preceded by the words 'class
Thing' or 'modify Thing' and finished with a semicolon. If in
principle the material could be anywhere, that makes it not just
harder to read the code, but also harder to "trust" the code. (Or as I
normally say "brain" the code, which requires a confidence that
nothing's been missed.)
A more significant problem, for me anyway, is the absence of clear
rules about syntax: the whole pretend NL bit.
It boils down to the same thing conceptually: sometimes less freedom
and strict rules is actually a good thing.
Andrew Plotkin
The latter. I claim that keeping code readable is almost entirely a
matter of what the author does -- not how the language is designed.
Particularly in the matter of code ordering.
(I note that Intercal and the other deliberately-awful languages don't
focus much of their awfulness on code ordering questions. If I were
going out on a limb, I would say that this represents a subconscious
recognition that no languages are specifically *good* in this area,
i.e., they're all just about the same...)
(I'm sure somebody will take up the challenge of finding or designing
a language which forces you to arrange your code badly. And no, COME
FROM isn't it.)
--Z
--
"And Aholibamah bare Jeush, and Jaalam, and Korah: these were the borogoves..."
*
You don't become a tyranny by committing torture. If you plan for torture,
argue in favor of torture, set up legal justifications for torturing
someday, then the moral rot has *already* set in.
Adam Thornton
Andrew Plotkin <erky...@eblong.com> wrote:
>(I note that Intercal and the other deliberately-awful languages don't
>focus much of their awfulness on code ordering questions. If I were
>going out on a limb, I would say that this represents a subconscious
>recognition that no languages are specifically *good* in this area,
>i.e., they're all just about the same...)
Piet imposes some interesting aesthetic constraints on ordering.
>You don't become a tyranny by committing torture. If you plan for torture,
>argue in favor of torture, set up legal justifications for torturing
>someday, then the moral rot has *already* set in.
How fortunate for us that the justifications are being put to good use.
I hate to see wasted effort.
Adam
Adam Thornton
<steve....@gmail.com> wrote:
>It boils down to the same thing conceptually: sometimes less freedom
>and strict rules is actually a good thing.
alt.sex.bondage is ---> *that* way.
Adam
Daryl McCullough
>
>Here, Daryl McCullough <stevend...@yahoo.com> wrote:
>> Andrew Plotkin says...
>>
>> >(Currently dealing with the hardest-to-read code I've ever been
>> >professionally required to understand. It's Java.)
>>
>> Are you saying that Java is the hardest-to-read *language*,
>> or that the particular code samples that you're looking at
>> are hard to read?
>
>The latter. I claim that keeping code readable is almost entirely a
>matter of what the author does -- not how the language is designed.
>Particularly in the matter of code ordering.
Oh, okay.
I don't have a strong opinion about Inform 7, but it seems
to me that the fact that Inform 7 code reads like natural
language doesn't really help in the readability of code.
Each particular *line* may be readable, but it is rarely
the case that "unreadable code" is unreadable because
it is hard to understand what individual lines of code
mean.
steve....@gmail.com
> [T]he fact that Inform 7 code reads like natural
> language doesn't really help in the readability of code.
> Each particular *line* may be readable, but it is rarely
> the case that "unreadable code" is unreadable because
> it is hard to understand what individual lines of code
> mean.
Wow. That's a really great way to put that point, Daryl. Kudos, and
thanks. It's a really good way of relating NL to code-readability.
ChicagoDave
> The latter. I claim that keeping code readable is almost entirely a
> matter of what the author does -- not how the language is designed.
> Particularly in the matter of code ordering.
>
> (I note that Intercal and the other deliberately-awful languages don't
> focus much of their awfulness on code ordering questions. If I were
> going out on a limb, I would say that this represents a subconscious
> recognition that no languages are specifically *good* in this area,
> i.e., they're all just about the same...)
I have this battle often with other senior developers and architect
level consultants. I have always argued that making code simple and
readable takes precedence over using complex patterns and language
features. Or in lieu of simplicity, commenting thoroughly is a
necessity.
In the end, the junior to mid-level programmer is going to be asked to
read and maintain your code. It's my belief that most code should be
written to this level of reading.
I think the argument that COBOL has survived is a good one, although I
wouldn't wish it on anyone.
As for Inform 7, I think it's a paradigm shift in many ways, not the
least of which is grammar confusion.
I can see how some people might find I7 difficult. But I also believe
it's the best balance between ease of use (for non-programmers) and
capability (for experience IF authors).
David C.
Andrew Plotkin
I think that the fact that each line is readable helps overall. It
doesn't make everything perfect, but even a fractional improvement
per-line is a significant improvement to the whole.
--Z
--
"And Aholibamah bare Jeush, and Jaalam, and Korah: these were the borogoves..."
*
Mike
However, you still need to know how the language operates to be able
to comprehend fully how it works. To take an example: A line in the
source text reads:
<code>
After taking inventory:
say "Altogether, you've got [the player's cash] on your person."
</code>
You can deduce that this is supposed to tell the player how much cash
the player is carrying. However, from this line alone, you do not
know by what mechanism this is achieved. You need to know about text
substitutions where [some text] appears in the say statement. In
addition, you need to know that "the player's cash" is not a built in
phrase but intstead it is determined by a "To decide" statement.
<code>
To decide what price is the player's cash:
let sum be the total price of money enclosed by the player;
decide on sum.
</code>
Even then, to understand what this code achieves, you need to know
about temporary variables, that somewhere some things have been
defined as "price" and "money" and you need to understand about
"enclosure."
As someone who came to Inform 7 cold without any knowledge of Inform
6, my experience is that you can more quickly pick up how the system
works and gain a high level understanding of how the source text
works, something that would be much more difficult if you were looking
at the source code equivalent in Inform 6. But simply because you can
look at the source text and make sense of it, does not mean that you
understand it. With the excellent help documentation and worked
examples, it is fairly easy to progress from "sense" to
"understanding". Trying to do that with one of the worked examples,
such as When In Rome or Bronze would not assist in that process. I
see them more as something to come back to when I have begun to
understand what the language achieves.
Victor Gijsbers
> (I'm sure somebody will take up the challenge of finding or designing
> a language which forces you to arrange your code badly. And no, COME
> FROM isn't it.)
Does Befunge count? (http://en.wikipedia.org/wiki/Befunge) Having to
arrange your code on a 80x25 rectengular grid might harm readability a
bit. Esepcially if it's a relatively large program that will only fit if
you reuse instructions by making them approachable from different sides. :)
Regards,
Victor
Jeff Nyman
> Anyone else noticed that Inform 7 game source is really hard to read
> sometimes?
I most definitely have noticed this. I would maintain, however, that this
can be more or less speaking to how an author chooses to break up their
source text, and how they choose to compartmentalize it (i.e., breaking it
up under headings), rather than an inherent aspect of Inform 7. In other
words, Inform doesn't force you to write "sloppy code," in my opinion, but
it can "encourage" such behavior.
I think you can find good examples of Inform 7 source that have been well
constructed. Some partial code that was released for "Anchorhead" (the
Inform 7 version, obviously) is, in my opinion, an excellent model for how
the headings should be used. The source text for "An Escape to Remember" is
also another good example of how source text can be intelligently put
together. I found these very useful for learning some aspects of Inform 7.
While you picked up on "When In Rome", I think you might find "Damnatio" or
especially "Bronze" easier going.
> unclear code is much easier to produce with Inform 7 than with just about
> any language I've used.
Speaking as someone who learned TADS 3 and Inform 7 largely from the ground
up and roughly at the same time, I can say that one techinque I use is to
read existing source code and build up my learning from there. In fact, I
have recreated large portions of existing games in my attempts to learn.
That's how I learn most languages.
I can say that it was often easier for me to learn from the TADS 3 code
because it had structure that I could count on, often *independent of the
author who wrote the code*. That's an important aspect to how systems adhere
to some form of code readability. (I looked at "Return to Ditch Day", "I
Must Play" and "Square Circle" -- all by three different authors.) While I
did have to jump around multiple files to find what I wanted, I had a good
clue as to exactly what to search on to find what I needed.
One aspect of Inform 7 that I think can (not *must*, but *can*) "encourage"
this (for lack of a better term) is the fact that you can't break anything
up into multiple files. That's just my opinion and is obviously not some
categorical fact. The Index can help you find some of the major "objects"
but actions taken on or with those objects may have been scattered around by
the author. Sometimes multiple files can help compartmentalize better,
keeping related aspects together in a slightly easier fashion.
The other aspect is that you can write Inform 7 source text as a form of
"stream of consciousness" (again, for lack of a better term) such that you
can write aspects of an object (or things that have to do with that object)
when you happen to think of it, rather than having to keep everything
encapsulated within an "object definition." I've found this can lead to
"scattered source." How scattered it actually is, however, goes back to how
the author chose to structure their game's source.
- Jeff
Andrew Plotkin
I thought about Befunge. I've never tried to understand (or write) a
Befunge program, but it seems to have the same kind of locality
constraints as any other line-by-line imperative language. (Crossing
lines of execution seems like more of a hardship for writing the code
than reading it.)
The real trouble (which I didn't realize until just now) is that it
lacks any native notion of goto or gosub. *That's* the code
arrangement stumbling block -- you have to pile things together or
replicate them.
(Where the two-dimensionality comes in is making it possible to write
programs *anyway*. You can synthesize these things with lines of
trampolines (which can intersect pretty well) and conditionals
(because you can fit several areas of code together and have them all
sufficiently adjacent to each other.)
--Z
--
"And Aholibamah bare Jeush, and Jaalam, and Korah: these were the borogoves..."
*
If the Bush administration hasn't shipped you to Syria for interrogation, it's
for one reason: they don't feel like it. Not because of the Eighth Amendment.