Change in coreboot[master]: Documentation: Codify some guidelines for headers and chain-including

[Julius Werner (Code Review)]

Julius Werner has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/50247 )

Change subject: Documentation: Codify some guidelines for headers and chain-including
......................................................................

Patch Set 2:

(1 comment)

Patchset:

PS2:
> Sorry, more serious: Before I agree to any rule about any sorting, I need to see any argument _for_ it. Maybe you know the answer: Is there an effective benefit in alphabetical order?

Well, I think it helps read the list of headers and check whether a specific header is already in there. I don't really feel like it's a hassle either, I just do it automatically when I write a new file. (If you're just touching an existing file and someone asks you to alphabetize headers that weren't before that's a different thing, of course, you should generally not be made responsible to clean up style in stuff you didn't write originally.)

Would you be okay if I just made it say that other orders are okay if they're intentional (e.g. something like "They should generally be sorted in alphabetical order, but authors are free to group them in thematical blocks when desired. In rare cases technical constraints may mandate an order, which should be clearly documented with comments.")? I think people generally just dislike when they're shuffled completely randomly, or when they used to be alphabetized but then someone else came along and just added a few lines onto the end for no reason. If you group your headers with some intentional order in your file that's not strictly alphabetical but makes sense, I don't think anybody should have a problem with that.