variable name length fallacy in docs

[oaken-source]

From the documentation:

Writing programs with short cryptic variable names instead of long descriptive ones does save space. This is old school programming, where squeezing every byte out matters."

This is actually not true. You argue that the disk space back on the Mainframe at home is unlimited, where the disk space on the Vessel is quite small, which is true, but in the 60s and 70s nobody would have sent an interpreted language on a spaceship. Instead, everything was compiled down to machine code, which does not retain information like variable names, so longer or shorter names would not change the size of the program at all, instead, the number of instructions matters.

I dislike the idea of advertising this fundamentally flawed style of programming today, and I think the corresponding section in the docs could be improved.

Thanks!

[Dunbaratu]

It won't be improved until it becomes false. The old school programming it's mimicking is more like basic, not assembler, where people did in fact do it that way.

As to the argument that nobody sent interpreted code on spaceflight, that is true. But the comment in the docs is true FOR KOS, because this is one of the areas it's not being realistic in.

I despise the unrealistic fact that it makes you pay disk space for well formatted and explanatory code, and it's a point of contention between me and some of the other devs.

But the solution is not to falsify the docs. What the docs are saying IS true about how kOS is working. I wish it wasn't. But it is.

[abenkovskii]

I personally agree with @Dunbaratu: making players pay for well formatted code is a bad idea.

[oaken-source]

I am not saying that the section is wrong for kOS, I am saying that the argument is flawed and that the limitations in place have nothing to do with "old school programming" or even space travel, and should not be justified as such.

[Dunbaratu]

You are incorrect when you claim that the comment meant "space travel" when it said "old school programming". That's not what it was referring to. It was referring to old crappy BASIC interpreters and the like.

[Dunbaratu]

By the way, kOS is compiled to something more like java bytecode or .Net's CIL - an object-aware runtime in which the length of variable names is actually retained - which is why KSM files aren't nearly as much of an improvement in program size as I would have liked - they only mention the full length string once in a lookup table, and then just index by number into that table, so there is some savings there if you use the same long variable name again and again, and there is some savings in not having comments or indentation, but with so many people in the habit of writing code that uses awful mathematician-style abbreviations and single-letter variables, for the code most people are writing it hasn't helped.

[oaken-source]

Hm, maybe we can at least agree that the section I quoted above is badly worded and could be improved? I would suggest replacing

Writing programs with short cryptic variable names instead of long descriptive ones does save space. This is old school programming, where squeezing every byte out matters.

with something like

You may have to keep your programs as short and concise as possible because squeezing out every byte matters.

Just to make it read less like an advertisement for poor programming practices.

[Dunbaratu]

You make the claim that the current wording is an advertisement for poor programming practices. The opposite is true. It is in fact slightly deriding that practice - note the use of "cryptic" to describe short names and and "descriptive" to describe long ones. Your new proposed wording, a neutral statement that drops those terms, is actually a better advertisement for the poor practices than the original statement because the original statement slightly derided them. There is no praise whatsoever for these programming practices in the original statement other than that which you read into it.

This issue is a non-issue.

If and when the point becomes moot because I can convince the others that the disk space limits are unfairly small (because we're counting bytes of source code, not bytes of ML code so the limitation to era-appropriate storage sizes is just not appropriate), then comment will just go away entirely from the documentation because it won't matter. Until then, the claim that it's somehow praising the old practice of having to use cryptic variable names and squeeze out every byte from your source code just isn't true. It's actually a bit derisive of those practices.