An initial proposal for coding standards.

[robertu94]

This example standards is contributed so as to have a concrete point of comparison. @ProtractorNinja @mdclyburn , What do you think?

[ProtractorNinja]

I think that this would be a lot more helpful if it included a summary of the sort of rules that someone would need to read to get started quickly, without reading the entire Linux Kernel style guide.

Also: can you move the list of ignorable chapters into a bulleted list?

Please start giving your submissions a serious once-over for grammar, spelling, and consistency before you submit them. "Do not specific apply" is a typo, "namely" isn't used correctly, and there are a bunch of little errors and inconsistencies in all of the other sections.

[robertu94]

I have made several of the fixes that you have suggested, but I have not summarized the Linux Kernel style guide. The style guide is not that long, and I would rather have people read the official version than have two different versions that could be possibly interpreted differently. If @mdclyburn agrees with you, I will make this change.

[mdclyburn]

We should, at the very least, have the most important guidelines spelled out in our own documentation. We do not have to copy the entire kernel style guide. I like to think that we are serious, but we are not that serious.

I am of the opinion that we don't exactly need to pick a style guide to follow. Do we really want the bulk of an entire style guide (regardless of whether we author it or not)? Sure, we can use the Linux kernel style guide to fall back on, but we should not have to even mention that we follow their coding style. I really just want the most obvious things stated.

• indentation
• curly brace style
• variable naming
• function naming
• block structuring
• loops
• other things I am missing

Looking back at my work on the LaTeX style guide, I realized that I want to provide another layer of abstraction over it because we have another goal here:

We want others to contribute. Walls of text scare people away.

[ProtractorNinja]

@mdclyburn said what I tried to back in #36 a lot better than I managed to.

I think that my initial suggestion from back then (which was to adopt an external guide) wasn't a good idea, and that we'd be better off with a list of core rules and few lines describing our purpose. Like he said -- we want to make contribution as easy and straightforward as possible.

[ProtractorNinja]

Again, I think this guide would be much improved if we ditched the reference to the Linux Kernel style guide and replaced that section with a summary of our style preferences (and a note to make code pretty if something isn't specified). It should be easy, not annoying, to contribute well.

This document is heavily affected by many issues I've already raised in #63: I don't like our current rules about heavy tests and fully-buildable code. Because such issues are not strictly related to this document, I'll be adding more thoughts to issue #63.

[robertu94]

Heavy tests and buildable code are essential to functional code. Consider the resources that were "test-lite" that came prior to the Hack Pack, less than half of them compiled let alone produced correct output. Even something that was more rigorously vetted like the USACO documentation has code that flat out didn't work because no one bothered to write an implementation and test it (see page126).

Kernel style, while heavy, is almost completely unambiguous. It is better to have rules and not need them, to want them and not have them. As for needing to read the whole Kernel style guide, you can get very close to correct style using automated tooling that exists on almost every modern platform that can implement the style. This lessens the need to closely read and memorize the style guide. Finally, if we are going to essentially use their style anyways, we might as well give them credit.

[ProtractorNinja]

Whether or not we need tests is a problem for #63. I've mentioned my thoughts on them there (basically: I think forced testing is the wrong solution to the problem of quality submissions).

Kernel style, while heavy, is almost completely unambiguous. It is better to have rules and not need them, to want them and not have them.

I disagree in our case. We're not running a large-scale project. We don't need utter unambiguity. We don't need One True Coding Style. We just need a quick reference for the kind of style we'd like to see. A few rules are nice, but our project won't need more than what I've suggested until we run into trouble.

As for needing to read the whole Kernel style guide, you can get very close to correct style using automated tooling that exists on almost every modern platform that can implement the style. This lessens the need to closely read and memorize the style guide. Finally, if we are going to essentially use their style anyways, we might as well give them credit.

Then we can cut out the middleman. All we need is...

Please ensure that your submissions are clean, compact, and easy to read. We ask that you adhere to the following style guidelines, inspired by the Linux Kernel style guide, to help in that goal. If you're interested, here also are a few commands to help automatically clean up your code: (...)

There are no downsides.

[robertu94]

I am willing to accept the compromise that you propose regarding Kernel Style.

I still disagree about tests, but we can hash that out on #63.

I'll update the pull request when I get the chance.