Choose a coding style

[escondida]

Frotz has had a lot of contributors over the years, and there's never been any standard for what the code should actually look like. It's understandable; it's an old project. However, this can get distracting when indents within even a single function use spaces and tabs (dogs and cats living together, mass hysteria!) at random, have inconsistent bracing, and so forth.

Fortunately, indent(1) and find(1) exist! I propose that we choose a code formatting standard and stick with it, starting by running indent over the project.

Personally, I vote for K&R style, since Kernighan & Ritchie were pretty good at C. Pie-in-the-sky I'd modify that to one-true-brace style, but as far as I can tell neither GNU nor BSD indent supports that.

The magic invocation I've tested is this: indent -kr -bad -c1 -cd1 -cp1 -nlp -ts4

The switches beyond -kr are to make the output a bit more like that of the book, rather than GNU's baffling choices (indenting comments halfway across the screen, etc.). -ts4 means that indent will use tab stops of 4 spaces for its work; this should have no effect on how the code actually appears in your editor.

I'm happy to do the work myself, too, though I should note that I'm not really comfortable with suddenly appearing to take credit for every single line of code in the project...

[DavidGriffith]

I'll play with your suggestions and do commit something in a few days.

[tkorvola]

The industry standard tab stop is 8 spaces. However, it is generally best to indent only with spaces. Both -nlp and -lp seem to make a mess - I am not sure which is worse.

[escondida]

tkorvola, as mentioned setting that won't futz with how tabs are displayed when you're actually editing the file, it's just for its internal black magic. -nlp seemed the lesser of two evils to me, but eh, either way.

I disagree on "best to use only spaces"; so much of frotz's 2-space indent vs. 4-space indent (in the same files) weirdness could've been avoided by tabs, and each person can have tabs appear to be as many spaces as they like without anybody else even having to know about it.

[tkorvola]

Using tabs of wrong size messes up alignment of lines with different indentation. Then again, using -nlp destroys any such alignment. Line length computation is of course also affected. Code indented with tabs will in any case look somewhat bad in tools such as diff or git blame that add a prefix to lines.

[escondida]

tkorvola, I retract my suggestion to use -ts4.

I've never had a problem with either diff or git blame and tabs. Both add a prefix of uniform length to avoid such problems, in fact!

The tab character is there specifically to represent 1 level of indentation; that's been its typographical meaning for a long time. Sure, you can achieve a similar effect with multiple spaces, but it's less flexible (since users can't adjust indent width to taste). One contributor wants to look at 2-space indents? Fine, they'll see them how they please thanks to their editor. Another wants 8? Fine, they'll see them how they like, with no need for the code itself to be changed to reflect that.

Spaces also pretty much require a fixed-width font. Granted, it's unusual to program in proportional fonts, but at least one programmer's editor (acme) uses proportional fonts (and tabs) by default.

[tkorvola]

I don't think tab has a typographical meaning. It is a leftover from typewriters, where it was used for tabulation. Anyway, the problem is not representing block indentation, it is representing alignment. For that we don't currently have anything better than spaces with a fixed width font. So it's a trade-off: if you want adjustable indentation and proportional fonts you'll forgo the ability to align things like

foo * (barbarbar
       + bazbazbaz)

(it is not always a function call that needs line breaking) and should lay them out like

foo * (
  barbarbar
  + bazbazbaz)

which is a bit longer. Trying to fit it in two lines without alignment, i.e.,

foo * (barbarbar
  + bazbazbaz)

is ugly and confusing.

[nsajko]

May I suggest clang-format? It is more powerful in many ways (if a bit complicated) than indent. It can take care of indentation, alignment (with tabs, too) and line wrapping. It normalizes code making it easier to read and taking the burden of thinking about what style to choose off programmers.

For a nice configuration with tabs, see this commit message:

https://github.com/nsajko/freediag/commit/5512c74c059b561f62ca1a4c31355c8981a7329f