Formatting the code

[pepe]

I find the spork's formatting very nice and as god @bakpakin intended. I use @andrewchambers wrapper as a post-write hook on all my Janet files. As a community, let's embrace this style and use it on all of our codes. But maybe there are some issues I do not see?

What are your thoughts?

[sogaiu]

I have mixed views on this.

In curly brace languages it is often easy to add a line here and there and to comment things out. If code is formatted in the more-or-less mainstream lisp manner, it means lots of parens will eventually be bunched up at the end in some places. That makes for an unnecessary amount of work when trying to modify code for debugging / testing purposes.

I recently learned in a github issue for parinfer-rust about Gassanenko style which AFAICT is not mainstream. It seems to do things in a way that makes it easier to comment certain things out as well as add lines.

In Clojure there is the discard construct #_, so the commenting issue is less of a problem, but the "adding a line in-between" issue is not addressed by this AFAIU. (Note that AFAIU, Janet doesn't have a similar construct ATM.)

Personally, I think that different folks find different formatting to be easier to perceive. As I get older, I see that too many things on one line is definitely more taxing to parse than when vertically arranged -- i.e. horizontal lists are harder to scan and think about than those that are stacked vertically (and say, left-aligned).

Which list do you find it easier to perceive?

antelope butterfly caterpillar dragon elephant flamingo gorilla hippopatamus

antelope
butterfly
caterpillar
dragon
elephant
flamingo
gorilla
hippopatamus

Try counting the number of elements. I think you'll find that the horizontal list takes more effort because you have to scan varying widths. It's also harder with the horizontal list to look at every other item. I think a variety of tasks is harder with the horizontal list. (I think this is likely one reason bullet point lists in presentations are there instead of ordinary sentences and for documents that want to hide details, bullet point lists may be used less often ;P)

I think at the moment, I seem to not be able to handle as much as what I see in other folks' code on one line and looking at my own code, I find it to be different than many other folks'.

The point of the formatting remarks above is to mention that perception varies and if one values clarity, then the perception of the folks doing the maintenance should perhaps be a relevant factor in how things are formatted.

I used to think that it would be possible for each person to be able to specify unambiguously a style for themselves and that a capable configurable formatter would be able to reformat things to a given user's tastes. In theory then, if one were working on a project jointly with others, if the project had an agreed upon canonical unambiguous format, tooling could reformat to this style before allowing a commit. When working on code locally, one could reformat in a preferred style.

I no longer think this is possible because I don't think I can unambiguously spell out a set of rules that could be encoded / configured for a formatter -- to be clear, I think it might be the case that someone else could for their tastes. I format things and observe the results and ask myself whether I find one way to be easier to perceive / clearer than others. To complicate things, I don't think this necessarily stays the same over time.

Also, once one adds line length limits, I think this problem becomes even more intractable (and I prefer <= 80 columns when possible because I value side-by-side comparisons and for some other reasons including there being too many things (for me) on one line as hinted at above).

I am ok with trying to match formatting if contributing to someone else's project -- for this, it would be nicer to have tooling. I'm not so ok with having to format code I have to be the primary maintainer of -- I think it won't work out so well.

[pepe]

Thank you for your reply.

I am aware of some problems you describe; some are new ones for me—still a lot of food for thoughts.

But can I ask you about the particular problems you have encountered when using spork/fmt?

And do not forget EJIFG!

[sogaiu]

I haven't used jfmt (spork/fmt) enough to have a lot of data.

I do have one example. So it turns out I use a tool that treats certain types of content within comment blocks as tests. So when I have something like:

(comment

  (+ 1 1)
  # => 2

  :hi

  )

The first form in the comment block, (+ 1 1), is treated as a test and the comment right after it is parsed to obtain an "expected" result.

When I use jfmt on the above code, I get:

(comment

  (+ 1 1)
  # => 2

  :hi)

Note that the closing paren has been moved.

In Clojure a similar thing occurs when using parinfer. There is a work-around there which is to put a comma (or some other appropriate form) before the last paren. I'm not sure I want to have to do that sort of thing in my own Janet code. There is no comma-equivalent, but I suppose a single colon might work...

[pepe]

The straightforward solution for this problem I see is to use a comment just before the last paren, even with some "special" char to indicate the end:

(comment

  (+ 1 1)
  # => 2

  :hi

  #/
)

But I can understand if it is not good enough for you. Also, the last paren won't stay on the tab and move one line up.

[yumaikas]

Chalk me up for someone who's not super into the notion of auto-formatting all the things right now.