I've wondered a bit about this as I write a few packages. I'm a bit pleased to see order-by-usage suggested--because it should be formatter/linter-enforceable.

On the other hand, it's also common to interleave comments; I'm less sure if a formatter can just optimistically move the preceding comment, if any, any time it reorders arguments? :)

@abathur Although there's a few common patterns comments fall into, they can also get quite convoluted: see ffmpeg for a gnarly example. This will probably be quite a tricky problem to solve correctly (unless we decide to change the format of packages to something more structured).

Yes. I thought about commenting about semantic groupings, though I waffled since they might actually still group well enough by first use. (Though, no--I hadn't noticed how gnarly ffmpeg is).

I guess it might be easier to address with a linter--since it can just complain that the order is wrong and make a human sort out t he comments--as long as it can respect the semantic-grouping concept.

I see occasional chatter about docstrings--I hope a principled solution could fit there, if nowhere else.

ffmpeg is definitely the exception, not the norm. I'm more accustomed to seeing fairly straightforward examples that would likely stand up to this kind of treatment. Presumably you've had a similar experience.

What I'd like to see is the whole callPackage convention being replaced with a structured package format, with configuration à la Gentoo's USE flags. It's a shame that the proposed config DSL hasn't yet appeared, as I feel it would really help with some of these problems. A structured config format could have these comments instead be docstrings, as you said, allowing them to be queried — again, as on Gentoo:

v@gentoo ~> equery u coreutils
[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset                             ]
 * Found these USE flags for sys-apps/coreutils-8.32-r1:
 U I
 + + acl       : Add support for Access Control Lists
 + + caps      : Add Linux capabilities support in output of file utilities (ls, dir, ...) via sys-libs/libcap
 - - gmp       : Add support for dev-libs/gmp (GNU MP library)
 - - hostname  : Build the hostname program
 - - kill      : Build the kill program
 - - multicall : Build all tools into a single `coreutils` program akin to busybox to save space
 + + nls       : Add Native Language Support (using gettext - GNU locale utilities)
 - - static    : !!do not set this during bootstrap!! Causes binaries to be statically linked instead of dynamically
 - - test      : Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
 - - vanilla   : Do not add extra patches which change default behaviour; DO NOT USE THIS ON A GLOBAL SCALE as the severity of the meaning changes drastically

Also I am saying how it is but I don't think we can enforce this at all or people are getting mad.

For now, it's a guideline, not a rule. Later, we can have formatting tools apply the reordering for us.

I'm not really sure why you'd think people would be mad at having some actual coding conventions, though. The lack of any is a common complaint.

This is, at its core, a two line change. I've reached my limit with how much bikeshedding I'm willing to deal with at the moment, so I'm leaving it to someone else to carry to the finish line if they want this merged. This kind of feedback is extremely draining to engage with, and seriously demotivates me from contributing.

This is, at its core, a two line change. I've reached my limit with how much bikeshedding I'm willing to deal with at the moment, so I'm leaving it to someone else to carry to the finish line if they want this merged. This kind of feedback is extremely draining to engage with, and seriously demotivates me from contributing.

It is not just a two line change. This impacts everyone that contributes to nixpkgs and if we do not have the right tooling first then this kind of guideline for enforceable at all.

If we have a formatter that does this and most people can agree on using it then we can make the formatter a hard requirement.

Right now if I would suggest people to sort their inputs in a PR review I would start a lot of bike sheeting with a lot of people and they would discard my reviews even more.

It is not just a two line change. This impacts everyone that contributes to nixpkgs and if we do not have the right tooling first then this kind of guideline for enforceable at all.

That is okay, writing it down is a good start.

Right now if I would suggest people to sort their inputs in a PR review I would start a lot of bike sheeting with a lot of people and they would discard my reviews even more.

Well, you don't need to require it. 100% compliance doesn't have to be the goal until it is supported by tooling. It could be a request on new packages, or a suggestion on fixups. There is room for discretion.

@SuperSandro2000, we can't wait for perfect tooling or block improvements in cases where 100% compliance isn't feasible.

Right now if I would suggest people to sort their inputs in a PR review I would start a lot of bike sheeting with a lot of people and they would discard my reviews even more.

Nixpkgs is huge and broad. If the inputs are getting unwieldy, then you can say to sort if it improves comprehension, but I don't think this is true across the board. Also, you can convey that something is not a blocker (I usually say, I don't feel strongly about something). I think it's important for maintainers to have some "ownership" over the style of code they use.

@SuperSandro2000 I agree it would be nice for some conventions to be well defined, but the nature of nixpkgs is that it's a "living document", in the packages it contains and the conventions it adheres to. Like @grahamc said, this is a step in the right direction, and overall improvement.

Maybe one day we will be like elm, where the style is already determined for everyone, and adherence will be easy because any nix command will auto format your code. Until then, incremental improvement is always a good choice.