clj-commons / clj-commons/formatter

Feature prioritization

Open
#11 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
35
Forks
1
PR merge metrics
No merged PRs in 30d

Description

I see that communication on this project appears to have slowed down, and as an unknown Clojure developer, that saddens me. So, I'd like to try to stoke the fire a little and propose a way to get out of the deadlock that seems to have occurred on a number of issues.

In some cases, two features we would like to have are *impossible* to meet at the same time. For example, supporting semantic indentation cannot occur without either versioning the tool or supporting configuration.

It's difficult to move forward regarding the miscellaneous trade-offs without establishing which features are most important. For example, I think that looking similar to existing styles is less important than surviving language evolution. Judging by the other issue threads, that is not a universally shared belief.

Here's how I would begin prioritizing... just to kick things off:

1. Standalone specification, independent of its implementation.
2. Specification should be forever version 1.0.
3. Specification must not be configurable.
4. Specification must be able to be implemented efficiently in many environments.
5. Specification should be easy to implement efficiently in many environments.
6. There should be only exactly one acceptable way to format a non-comment.
7. When comparing two style options, select the option that produces smaller diffs.
8. If diffs are equivalent, select the option that produces fewer lines.
9. Comments should not be modified in any way, if possible.
10. A command-line tool should accompany the specification on release as a means of validating ease of implementation and edge-case handling. It can also be used as a bridge to native support in various IDEs.

Notably excluded:
1. Semantic indentation -- Incompatible with 2) and 3) above. If someone wants this, or to extend the specification in a configurable way, that's their prerogative.
2. Ubiquity -- Existing projects probably won't change, and some people will never use something without semantic indentation.
3. Semantic canonicalization (ex. ordering of ns forms). This is at odds with 2) and 5), as it requires special casing forms that are known to have ordered-values-that-are-not-really-ordered.

Some design decisions get made easier by the above. For example, how long should lines be? 7) and 8) take priority, so you could take a bunch of projects in the wild, run a formatter with a variety of line lengths, and choose whatever is working the best.

I appreciate that there are people thinking about this problem, and I'll end up using whatever you all decide on, regardless of if makes the same choices I would make. Thanks for reading, and good luck.

Contributor guide

No contributing guide indexed for this repository

Research direction

No files, tests, or implementation entry points are named. Treat the numbered priorities and exclusions as a design discussion first; a concrete formatter specification, implementation target, and acceptance checks would be needed before implementation can be considered done.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
15/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.