On Mon, Jan 20, 2025 at 06:26:06PM -0600, G. Branden Robinson wrote: > This style of feedback is producing a lot of churn. Jason's going to be > well into the v-teens before this patch is accepted, at this rate. > > It appears to me that what is happening here is that you are iteratively > developing a C code style guide under the banner of a man page review. > If Jason's okay with being the test subject for this procedure, then > there's not exactly a problem here, but if it were me submitting a man > page, I'd be getting frustrated by (or before) this point. I just "git > pulled" https://git.kernel.org/pub/scm/docs/man-pages/man-pages/ and > checked "./man/man7/man-pages.7", and practically _none_ of the rules > you've been stating to Jason is expressed there. > > I propose that the submissions of patches to the Linux man-pages not be > a black-box process, with you serving as the oracle that accepts or > rejects the input. I admit you're offering a bit more information than > a binary semaphore (ACCEPT/REJECT), but still, it would be better if > Jason, and others, had a "Linux man-pages example C code style guide" > document they could consult so that they could anticipate more of your > objections. > > If the construction of such a document is what this precise instance of > the process is groping toward, good. If not, then I suggest that it's > about time to prepare that document. > > I don't dispute that having a consistent style for code examples in the > Linux man-page corpus is worthwhile; I do think it will, ultimately, pay > dividends to harried hackers in a hurry. But it is precisely to the > extent that style guidelines are arbitrary that they need to be > documented and easily located. Thank you for standing up for me here, Branden. I am going to continue the back and forth with Alex, but I am frustrated by the process. It does indeed feel like a black-box process. I would have much preferred it if Alex had given me as many feedback points as possible each time. I really dislike it when I receive feedback and think to myself “I could have fixed this all the way back in v6. Why wasn’t I told this earlier?” I agree that having a “Linux man-pages example C code style guide” would be good. Alex said in another email “I'm just not looking at all the code at once, because it was highly unreadable.” It was impossible for me to produce code that was not highly unreadable to Alex. I say that because readability is in the eye of the beholder. When I first created the example program, I did many things to try and make my code as readable as possible. What I’m discovering now is that most of the things that I did made the code more readable for me and less readable for Alex. If there had been a “Linux man-pages example C code style guide” document, then I would have produced code that was more readable to Alex to begin with and I wouldn’t have been frustrated by the process.
