Hi Branden, On Mon, Jan 20, 2025 at 06:26:06PM -0600, G. Branden Robinson wrote: > [even earlier] > > Please group declarations of the same type in consecutive lines. > > Shorter type names up and longer type names below. For same length, > > please use alphabetic order. > > 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. Not really. I'm just not looking at all the code at once, because it was highly unreadable. Also, I expected that if I told all the issues I spotted at once, some might not make much sense at the same time. I like reviewing a small number of issues in each iteration, and don't load the contributor too much by pointing out 100 issues in their patch at once, which might get them the feeling of "hell, where do I start?". That coding style I already use it, and should be mostly the same as all other manual pages in this repository are following (except that maybe I haven't changed a few things in some existing code because the bar is slightly higher for additions than for existing pages (hysteresis comes into play)). > 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. Yep, the C coding style is not stated. But that doesn't mean the project doesn't have one. I haven't written in paper one of my own, and my C coding style is an interesting mix of <https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/CodingGuidelines> <https://www.gnu.org/prep/standards/standards.html> <https://google.github.io/styleguide/> <https://www.kernel.org/doc/html/latest/process/coding-style.html> <https://nginx.org/en/docs/dev/development_guide.html#code_style> <http://doc.cat-v.org/bell_labs/pikestyle> <https://www.cis.upenn.edu/~lee/06cse480/data/cstyle.ms.pdf> (in no particular order.) I should probably write my own somewhere, but that takes some time. I'll try to, at some point. > 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. > > On different, nerdier subjects... > > > Please don't use braces for a single statement. > > I think they are helpful for clarity. Yes, modern compilers will warn > about misleading indentation. I still think braces around any block > guarded by control instructions are a good idea for the human brain > interpreting code. In GNU code, with 2 spaces, definitely! :) In the civilised world, I think a blank line after the indented statement is enough for the brain to see the structure. On the contrary, I think that braces clutter the code, and take me more time to read. My brain doesn't even read indented stuff, on the premise that it's unimportant code (usually handling error cases, whose handling is unimportant for the main story). > And the presence of the braces costs nothing at > translation time. Does any compiler construct a new stack frame just > because it saw an opening brace in the input (that wasn't part of an > initializer)? I only do it for readability reasons. Performance should be the same. > > Please separate declarations from code. > > I think this is considered old-fashioned in some quarters. It has been > valid since ISO C99 to introduce declarations anywhere, and a common > style is to place them at, or adjacently to, the point where they're > used. I like C99's for-loop variables. But mixing statements and declarations makes the code less readable. I like being presented the protagonists of a function, and then told the story around those protagonists. Usually, by looking at the declarations, you can already guess most of the story. If the story is so deep that some protagonists have to be presented mid-story, the story is complex enough to be separated into a helper function. C89 declarations serve as a reminder that you should break your functions if they're big enough that you lost track of the declarations. > The traditional arrangement of placing all declarations at the top of a > function definition arises, as I understand it, from the limitations of > early compilers, which were often--and sometimes had to be--simple and > small. Don't forget that brains keep being simple and small. > When the compiler read the function definition, it could > generate an assembly language preamble for setting up a stack frame that > reserved all of the room necessary for any storage of automatic > duration, and then start translating statements into instructions at > once.[1] (A test of this understanding would be whether any pre-C99 > compilers rejected "late" declaration of automatic variables, but > happily accepted them for static or register variables, since those > would not complicate stack memory allocation. I'm not quite old enough > to say; for the first <mumble> years of my programming career, GCC was > the only C compiler I ever used.) > > Anyway, this is another of those matters of taste, so if mandatory early > declarations are to be the rule, you probably want to say so explicitly Yeah, there are many things I should mention there. > so that you're not mistaken for a grognard who either isn't aware that > ISO C99 happened, or, like Dennis Ritchie, refused to countenance its > its existence with a 3rd edition of its central textbook, and eventually > ran out of time to do so. (In a 2000 interview, he said it "needs to > quiesce for a while".)[2] Heh! While I wrote (literally) a couple of programs in the early 2000s with the help of my father, I didn't program again in C until after 2011. The first standard under which I programmed my third program (first solo programming) was C11 already. :-) To me, C89 is a dead language, and C99 is already getting into the same category. BTW, I joined WG14 (the ISO C committee) last year. :) See also: <https://thephd.dev/the-big-array-size-survey-for-c> > Finally, I'll note that asserting a dichotomy between "declarations" and > "code" can be misleading. Declarations can generate assembly language > too, and not just when they are coupled with initializers. I'd say > "declarations" and "statements" instead, Makes sense. > or avoid the issue entirely and > say something like, "group all variable declarations at the top of each > function". Have a lovely night! Alex -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
