Future of the project

[bbatsov]

After a long hiatus I'm finally trying to clean the backlog and improve the structure, examples and the rationale of the existing guidelines. I hope to get the document to a state which I consider good in the next couple of months.

There are two topics for the future that I wanted to discuss here:

1. (important) More editors. I don't want to be a single point of failure here, so I'd be my preference to have as co-editors (and admins of this repo) someone from Clojure Core and Clojure Commons. I'd like to nominate @puredanger and @danielcompton, if they'd be willing to accept this.
2. (optional) Transitioning the project to Clojure's GitHub org and (potentially) including it or some version of it under clojure.org. I guess that's mostly up to @puredanger, who expressed some interest in working in this direction a while back. I like the clojure.style domain and how the guide is presented there, but conveniently both clojure.org and clojure.style are using AsciiDoc, so I can imagine it will look more or less the same, sans the menubar. I'm fond of the cool and easy to remember domain, but I'm definitely not attached to it, as clojure.org would be the natural home for such a guide.

I consider the first item more important for a simple reason - anything can happen to me. That's why I historically avoided being the sole owner of any project I deem important. More editors will also add more credibility and clarity to the guide, especially if they are people like Alex and Daniel.

[puredanger]

That’s an interesting proposal! I’d be happy to adopt it into the Clojure site and it would be pretty easy to include as you say.

I think the only big thing to resolve would be the licensing / contribution question. The Clojure site repo content is EPL and governed under the Clojure CA. I guess if the style guide stayed in this repo, we could just pull it in and include it as part of the site build and that would still be fine according to CC if we attribute properly and then it wouldn’t be part of the clojure repo contents covered by epl. We would probably need to clarify things in a couple spots but that seems workable.

Could either leave clojure.style as is or redirect it to the Clojure site - that would be up to you. It is a cool link. :)

[puredanger]

And I’d be happy to be an editor with the caveat that I’m not likely to have a ton of time to invest in it, so would be great to vest this power with someone who did, whether that’s Daniel or someone else.

[danielcompton]

I'd like to nominate @puredanger and @danielcompton, if they'd be willing to accept this.

I'm honoured to be nominated and would be happy to accept 😄.

[bbatsov]

I think the only big thing to resolve would be the licensing / contribution question. The Clojure site repo content is EPL and governed under the Clojure CA. I guess if the style guide stayed in this repo, we could just pull it in and include it as part of the site build and that would still be fine according to CC if we attribute properly and then it wouldn’t be part of the clojure repo contents covered by epl. We would probably need to clarify things in a couple spots but that seems workable.

I'm not well versed in the licensing stuff, so I'll defer to you on that one. I was thinking that keeping the repo separate might be a good idea for one more reason - to avoid too many style-related discussion on the clojure.org repo. Not sure if that's a real problem, though, as for a while the guidelines have been fairly stable.

And I’d be happy to be an editor with the caveat that I’m not likely to have a ton of time to invest in it, so would be great to vest this power with someone who did, whether that’s Daniel or someone else.

Don't worry about this at all. I know you're quite busy and I don't want to burden you further. I'll still be around for the foreseeable future, I'm mostly looking to reduce the project's bus factor and to make sure that there a more editors that can approve a suggested change or tweak some example. The project hasn't required much maintainence in recent years, as Clojure has stayed very stable and the best practices for writing Clojure code have been pretty stable as a side-effect.

[bbatsov]

I'm honoured to be nominated and would be happy to accept 😄.

Thanks, Daniel! 🙇‍♂️

[practicalli-johnny]

The style guide is a wonderful collection of experiences gathered over the years, so making it part of clojure.org is a welcome idea, however, I assume the guide will have a good review to ensure its an invaluable resource for all.

Once the guide is added to the Clojure.org website, then it becomes more authoritative (even if caveats are added to the content) and I agree having the discussion before moving would be better.

For example, one recent addition to the style guide is worded in a way I think may be quite misleading as someone fairly new to Clojure.

I also find the good / bad wording a not that constructive. Do we need to include examples labelled bad, it would seem recommended examples are all that are required.

I will have time to review some of these styles over the holidays and can make some issues and PR's as I find them. We should also encourage more discussion around them too, to see if any changes are required.

[seancorfield]

There are definitely pros and cons to having the (community) style guide incorporated in some form into clojure.org's content.

Pros:

• It would likely stop a lot of the "how official/authoritative is the style guide?" questions since it would be assumed to be "official" to some degree.
• It would be easier for folks to find and stem "is there a style guide?" questions.
• It would "encourage" more consistency about how Clojure code is written because of those first two points.

Cons:

• There are some things in the style guide that don't necessarily reflect the consensus of the community at large so making it "more official" makes it harder for folks who disagree to heard.
• Similarly, folks who write open source in a style that doesn't conform to the style guide (for whatever good reasons they may have) are more likely to have to field questions (and issues and pull requests) about changing their code to match the "official" style guide.

Overall, a net positive, but I think some guidelines may be worth reconsidering if the style guide is given a more authoritative stamp, or at least updating to include examples and justification for an alternative style.

There's no question that addressing the first point, to reduce the "bus" factor, is definitely worth it.

[danielcompton]

I also find the good / bad wording a not that constructive. Do we need to include examples labelled bad, it would seem recommended examples are all that are required.

I understand your concern, and perhaps a better name could be chosen, but I think including counterexamples is good for helping people hone in on the suggested style.

[bbatsov]

Indeed. The good/bad wording is something I came up with in the original draft of the Ruby style guide, without giving it much thought. I think the important part is having examples and counter examples, how they are labeled exactly is not that big of a deal, as long as it's clear which examples are encouraged.

That's one of the great things about community-driven projects - there's always someone who can help make things better. :-)

I will have time to review some of these styles over the holidays and can make some issues and PR's as I find them. We should also encourage more discussion around them too, to see if any changes are required.

PRs and suggestions for improvements are always welcome!

[bbatsov]

@seancorfield Fantastic points! I completely agree with everything you've said!

Overall, a net positive, but I think some guidelines may be worth reconsidering if the style guide is given a more authoritative stamp, or at least updating to include examples and justification for an alternative style.

Yeah, totally. Obviously no guideline is set in stone and some things have been changed over the years as a result of the conversations we've had here. Btw, I've recently added a couple of "meta" sections that I consider very important:

• https://guide.clojure.style/#guiding-principles
• https://guide.clojure.style/#a-note-about-consistency

I've been also expanding the rationale behind non-obvious guidelines (e.g. why is a single segment ns a bad idea) and mentioning popular alternative styles (e.g. using just a single ; everywhere, using fixed indentation, etc). We're quite fortunate to be using a language where there aren't that many highly disputed style topics (like the infamous single vs double quoted string literals in many other programming languages), but it's highly unlikely that we'll ever get universal agreement on everything. Still, we have to give it our best shot.

[daveliepmann]

Hey folks, glad to see Bozhidar taking the long view of stewardship here :)

There are some things in the style guide that don't necessarily reflect the consensus of the community at large so making it "more official" makes it harder for folks who disagree to heard.

+1

I would prefer that the style guide be relatively minimal, so we capture the least common denominator rather than try for maximal coverage. In short, descriptivism over prescriptivism. I'm a huge fan of style guide, especially the version I encountered at the time I started writing Clojure! As a beginner it was a great way to discover idiomatic Clojure and functions like when-not. That said, I have to acknowledge that it's been strange over the years to recommend the style guide, then check back and find that the recommendations had shifted while I wasn't looking.

To that point: perhaps I'm imagining it but the trend over time seems to bend toward more linter-style rules ("namespace requires must be sorted alphabetically") rather than idiom ("we use this function for that").

For instance this new entry about including the optional parens in a threading macro reflects my (weak) preference, but feels like overreach. I wouldn't mind this in a style guide for a particular project or company but community-wide it feels strict. If the Clojure community wants to move towards a significantly more regimented, gofmt-like experience then an official Clojure team / clojure.org stamp of approval would help, but we should be clear we're making that decision.

Only one more example, I promise: are comp and partial really favored over anonymous functions? Again, I'm arguing against my own preferred style, because this rule seems prescriptive in a direction that I believe Rich and many (most?) Clojurists don't precisely follow.

[bbatsov]

To that point: perhaps I'm imagining it but the trend over time seems to bend toward more linter-style rules ("namespace requires must be sorted alphabetically") rather than idiom ("we use this function for that").

A fair point. Some guidelines are definitely more meaningful than others, no argument about that. It's hard to decide where exactly to draw the line, as I know that many people believe its easier for people to scan a sorted list of items. I recall in the past it was discussed to assign level of importance to each guideline as an alternative to removing non-essential guidelines.

Only one more example, I promise: are comp and partial really favored over anonymous functions? Again, I'm arguing against my own preferred style, because this rule seems prescriptive in a direction that I believe Rich and many (most?) Clojurists don't precisely follow.

Touche. Those should probably go away.

Again - you've got the power. As long as some people pay attention to those things and drive conversations around them we can always do something to improve the status quo. Admittedly, I didn't manage to allocate as much time as I wanted to the project (the curse of being involved in too many projects and having a FT job and real life as well), as it deserved, so any help is both welcome and appreciated.

[seancorfield]

@daveliepmann Brings up an interesting point: I think Rich is on record as saying he favors anonymous functions over partial (although searching for that discussion is eluding me right now) -- and that was a question that popped up during my REPL talk last night because I've switched from using partial a lot to using anonymous functions instead (partly because of Rich's comments and partly because I find the explicit use of arguments in the anonymous function replacement of partial to add more clarity of intent).

I haven't reviewed the style guide in-depth recently -- as Dave says, it has certainly grown over time and I'm sure I disagree with more of it now than I used to -- but I tend to refer folks to Stuart Sierra's Do's and Don'ts more than the style guide because Stuart's posts are more about idiom than style. Some of the things in the style guide are solidly on the idiom side of the fence and quite a bit of it is more in the realm of surface style and what I would consider personal preference (albeit many such items are the common preference of a large number of persons).

For me, almost all of "Source Code Layout & Organization" falls into the preference category (and includes a few things I disagree very strongly with but is mostly "meh, don't care"). Some of it is useful advice for beginners, especially coming from C-family languages that have very different layout guidelines for braces/brackets, but a lot of that section feels overly specified to me.

Having just gone and scrolled through the style guide... wow, it has grown a lot since I really spent any time studying it.

[bbatsov]

Btw, looking at the commit log there are very few new guidelines added in the past 5 years. I think most of the perception that the guide is bigger is probably related to the new layout with headings for each guideline (they used to be just bullet-points), and to having more examples/explanations. Then again, if you haven't visitted the guide since 2013 - a lot of new guidelines were added between 2013 and 2015. :-)

but I tend to refer folks to Stuart Sierra's Do's and Don'ts more than the style guide because Stuart's posts are more about idiom than style

Btw, I've incorporated a lot of his suggestions from the blog series here. Lots of great advice there!

For me, almost all of "Source Code Layout & Organization" falls into the preference category (and includes a few things I disagree very strongly with but is mostly "meh, don't care"). Some of it is useful advice for beginners, especially coming from C-family languages that have very different layout guidelines for braces/brackets, but a lot of that section feels overly specified to me.

I definitely understand your perspective. Probably I feel differently about this mostly because I also work on indentation engines (both in the Ruby community and here) and I know that a lot of people are very picky about those things, so I like to cover them in great detail, even if much of those is common sense for many people.

[seancorfield]

Fair enough @bbatsov the perceived size may indeed be due to the increase in formatting and the addition of examples and explanation text.

I used to write coding standards for a living (back in the early '90s, mostly for C and C++) so I certainly have opinions 😃

[bbatsov]

@seancorfield Seems to me you'd be a great addition to our editor team then! 😉 Let me know if want to be a part of it.

[seancorfield]

Sure. I'd love to help if you're happy to have someone this opinionated 😁

[bbatsov]

Those are the best kind of style guide editors! 😆

[puredanger]

I think rather than incorporating the guide into the main clojure site, we'd like to focus on updating how's it linked and presented. I'm going to take a look at that next week.

[seancorfield]

I think it would be very helpful to introduce a "summary" section at the front which is essentially just a bullet-point list of all the guidelines which would allow readers to quickly scan the "meat" of the guidelines -- what should or shouldn't be done -- and then readers can dig into rationale and examples (per the current document) if they want/need to.

Longer-term, I think it would be better to separate Clojure idioms from purely stylistic guidelines (so the summary would have two subsections, and the rest of the document would reflect that new ordering). The idioms should be non-controversial -- accepted "this is how we do it in Clojure" items -- and the stylistic guidelines can be more about choice or readability of code (the guide already discusses several such guidelines, offering alternative recommendations).

[practicalli-johnny]

Longer-term, I think it would be better to separate Clojure idioms from purely stylistic guidelines ... The idioms should be non-controversial -- accepted "this is how we do it in Clojure" items -- and the stylistic guidelines can be more about choice or readability of code (the guide already discusses several such guidelines, offering alternative recommendations).

Yes please. Idioms should be separate to style.

Would be great to ensure idioms and tools like clj-kondo are aligned (which it seems they mostly are at a glance)

[bbatsov]

I think it would be very helpful to introduce a "summary" section at the front which is essentially just a bullet-point list of all the guidelines which would allow readers to quickly scan the "meat" of the guidelines -- what should or shouldn't be done -- and then readers can dig into rationale and examples (per the current document) if they want/need to.

Doesn't the current TOC service this purpose more or less? I think the idea has merit, but I'm always wary of duplication that's why I went for the current format (as it was easy to generate the list you suggested from the headings in some section).

This Common Lisp style guide (which was one of the inspirational references I used), uses an approach where all examples and rationale are hidden by default, but I find this layout a bit extreme. It's also not that common, compared to other prominent style guides. In terms of general inspiration for the layout/structure my primary guiding stars were https://www.python.org/dev/peps/pep-0008/ and https://rubystyle.guide/

Longer-term, I think it would be better to separate Clojure idioms from purely stylistic guidelines (so the summary would have two subsections, and the rest of the document would reflect that new ordering). The idioms should be non-controversial -- accepted "this is how we do it in Clojure" items -- and the stylistic guidelines can be more about choice or readability of code (the guide already discusses several such guidelines, offering alternative recommendations).

I guess we'll need some clear definition of "idioms" in this context as depending on your perspective everything can go under "idiomatic usage" - e.g. function/macro idioms, data structure idioms, documentation idioms, formatting idioms.

Yes please. Idioms should be separate to style.

Similar to the previous point. I'll assume your're referring to idiomatic usage of say functions/macros (as in https://guide.clojure.style/#idioms), but if so - idioms are just one of the stylistic dimensions, so you I wouldn't say they are separate from style, but rather a subset of style. It's a "style guide" after all. :-)

[bbatsov]

Btw, I've just enabled the project's discussion board (see https://github.com/bbatsov/clojure-style-guide/discussions/) Seems to me it might be a useful (better?) place for discussions for obvious reasons. 😆