Aside, re lined-up code

documentation
1

Continuing the discussion from Doc examples: two^h^h^hthree questions:

This is not completely relevant to the other thread. Just replying for the sake of conversation.

Yeah, am aware of the practice, but I think it’s misapplied in that example. The code block is already isolated anyhow so it’s completely unnecessary, and all the spacing does in that block is to draw the eye to the parentheses, which is the least important part of the code. It has the reverse effect of the intent here, I reckon (and - yes - subjective).

Rules and practices are excellent. But one still needs to stop to think about whether applying them makes sense in a given situation. Very few of these practices work ubiquitously.

For these docs, I’d say it’s inappropriate. for your own code… I reckon if you need to be doing it, there’s a good chance the code ought to be refactored, rather than lined up all neatly. One generally shouldn’t need the “gestalt shift” in well-presented code.

And, yes, this is all a bit digressive :wink:

–
Adam

2

I disagree in this example. Once I’ve understood the premise of the code example, I can scan down the values “column” to see what evaluates to true, without needing to re-read the stuff around it.

It works for me, perhaps your brain works incorrectly, ahem, differently :stuck_out_tongue:

But all this feels like it could digress into a spaces vs tabs style religious debate and probably isn’t helpful for the public domain. I agree that we should keep the documentation examples free of this practice (I can submit to not needing to engage in that battle).

I should correct my misuse of the phrase “gestalt shift” - it’s not correct. Just gestalt in this case - just the shape of things.

1 Like