16

Lots of programming languages allow for different code styles that are all valid syntax. Often, there are many established code styles which all have their raisons d'être.

How should the community deal with discrepancies between styles in the Documentation feature? After all, people should be able to consult Documentation to learn about programming and code styles are an important part of that.

11
  • How about adding all style variations as an example?
    – Desdenova
    Jul 21, 2016 at 13:54
  • 2
    @Desdenova I can't add multiple lines in a comment, but I'd say the difference between the people who add a return between the parameters in a Java method declaration and the { character, and those who just put a space (which, I hold the strong opinion that it's the correct way).
    – gkubed
    Jul 21, 2016 at 13:59
  • 1
    Side-by-side comparisons would be luxurious to have, annoying to maintain though. StackOverflow could issue recommended code styles just for the documentation feature. pro: docs should not confuse newbies, con: needs community effort and voting
    – Daniel
    Jul 21, 2016 at 14:00
  • I think every section could have Style Guide exaples, I find it very effecient way to orgenize my code (Duh... but really - it does help me orgenize my code :) ), just like jQuery's guide. But eventually it's just a recommendation and it's not something that should be enforced - Unless there is real problems with the code indentions/alignment, this case the example should be edited, downvoted, or just removed
    – Alon Eitan
    Jul 21, 2016 at 14:03
  • 2
    @gkubed By code style I thought of different syntax doing exact same thing. Such as this: stackoverflow.com/a/24112640/771231
    – Desdenova
    Jul 21, 2016 at 14:04
  • 1
    {1,2,3,4}, { 1, 2, 3, 4 }... the inconsistency is killing me. Give democratic coding standards please.
    – user2176127
    Jul 21, 2016 at 14:23
  • What if (for Documentation only - not the Q&A SO) the code tags would apply either a default or a user-defined formatting, similar to most IDEs? That way I would always see that array as {1,2,3,4}
    – Ealhmund
    Jul 21, 2016 at 14:27
  • Applying formatting is a pretty complex thing and has to be implemented individually for most programming languages while taking "code style rules" into account
    – Daniel
    Jul 21, 2016 at 18:27
  • It'd be great to have code snippet fields with linting (do web-based linters exist?) checking the official code style rules.
    – jfrej
    Jul 21, 2016 at 22:49
  • More importantly, I've seen examples get rejected because of the coding style which is ridiculous - it means we're not providing valuable code examples (that will execute perfectly adequately) just because someone likes there code less hungarian-y Aug 3, 2016 at 10:32
  • To be honest i will just follow the language / framework default style. ANd people rejecting for bad code style should be considered as not constructive
    – Walfrat
    Aug 3, 2016 at 13:16

3 Answers 3

10

I agree that documentation should follow a common coding standard. It doesn't matter which, but it should follow one and only one. Unfortunately, there doesn't seem to be any way to add meta information to a specific dashboard. Maybe the dashboards should get the equivalent of tag wiki as found on the main site. Feature request?

A possible workaround in the meantime could be:

Create a separate documentation topic "Coding Standards" which documents the various Coding Standards for your language. Then either

  • wait for a day and then put a big fat note in the coding standard with the most upvotes that this is the standard all examples should follow or
  • link to the topic here and ask people to vote on it or
  • just decide alone and hope that people follow.

Any better ideas are obviously welcome.

4

There are two problems with declaring a single coding style:

  1. People won't adhere to it. It's hard to get random programmers to adhere to a single coding style when you can fire them. Getting them to follow a single coding style when they're doing unpaid work in their free time? Yeah, good luck with that...

  2. If you force them to, they'll just stop contributing. If you flat-out reject any change that doesn't follow the coding style de jure, they just won't contribute. Again, we're talking about unpaid work.

The absolute most you can do is just have a dedicated clique go around every night and adjust code to fit a particular style. But that requires a lot of manual grunt-work.

1
  • 1
    it works pretty well in other documentation projects. why shouldn't it work here, too? If I have to choose between examples in a coding style I don't like and examples in many coding styles I don't like, I choose the former. At least it's consistent then.
    – Gordon
    Jul 27, 2016 at 11:34
-2

I think most of languages have a coding standard defined on their own, so i don't see the point of SO choosing which one to follow.

In SO's spirit, if someone ask a question about the some point of coding style for a language, the good answer is a quote from the language's coding style guidelines, not a IMO you should write it like this. So i think it must be the same in documentation.

Of course some details like space before brackets, or line could be set here in SO may not be specified in the said guidelines. But i don't think we need to be that much specific.

We're not reading thousand lines of some application's code but an example with bit of text with a snippet code which won't ever be so long that we need to set every details of formatting. Then we will go to another independant example.

1

Not the answer you're looking for? Browse other questions tagged .