Coding style guide

[iteles]

• Tabs vs spaces (2 spaces please!)
• Semicolons please
• Let's stick to a standard in markdown (interestingly, @iteles uses _underscores_ for italic and @nelsonic uses *single asterisks*)
• Fully commented code
• What is a good commit message?

And many more including a guide for writing issues. Either way, this needs to be done by the summer.

[nelsonic]

@iteles I've adopted _underscores_ for italics now. You're right, its way better! :+1: :stuck_out_tongue_winking_eye:

[iteles]

:stuck_out_tongue_closed_eyes: It is better though!

[olizilla]

I've always preferred _underscores_ for italics, though I used to push for tabs over spaces. I still believe in the dream of an indentation character, but have long ago turned to the darkside of the 2 space indent.

How can we even semicolons though? Why not Standard JS? https://github.com/feross/standard

[nelsonic]

Come on ... 2-space indent isn't "dark side" As for the semicolons, I'm not convinced ASI consistent enough ... @Feross is unquestionably a smart guy with plenty of JS experience, but I've been bitten by a semicolon bug before and it wasn't fun. :disappointed: https://brendaneich.com/2012/04/the-infernal-semicolon/

[olizilla]

Drama added for emphasis. I used to tab, as it seemed the semantically correct character for the job, and all my editors were smart enough to deal, and it gave the reader the freedom to set the indent depth as suited them. Then I started writing JS for a living, and ultimately I couldn't deal with being the only tabster in a space-bubble.

The straw that broke the camels back was GitHub rendering tabs as 4 spaces which looks ridiculous with callback heavy code. That said, maybe that's a good thing, (i pathologically avoid nesting things as a side effect) and GH now deals with tabs sanely.

Anyhoo, I space now. There is value in adopting the prevailing code style of the eco-system you plan to swim in, just to lower mental admin of jumping between projects. Defining a code style is a good exercise for someone learning to code, so you can all evaluate the tradeoffs. Maybe it's an exercise for the summer, rather than in place at the start?

[iteles]

I have no problem with spaces, it's the lack of semicolons that freaks me out a little. I'm a fan of the pauses :see_no_evil:

[iteles]

Linked to https://github.com/dwyl/start-here/issues/41

[iteles]

What's the best term for this 'style guide' thing so that I can create a repo and make a documented start? Style guide works for visual components in my mind but there must be something better for code...

And should we have a repo for the visual style and a separate one for coding style? Will having them together actually make back-end developers more aware of the visual side of things (seeing as anyone focusing on the front-end will need to see both)?

[FilWisher]

https://github.com/Flet/semistandard is a fork of standard with semicolons on top. (I do realize the irony of forking a standard and changing it). Everything else is the same

[FilWisher]

Will having them together actually make back-end developers more aware of the visual side of things (seeing as anyone focusing on the front-end will need to see both)?

Separate repos makes more sense to me. If I'm supposed to be looking for JS rules and start reading through visual style because it's there and I have a short attention span, something doesn't feel right.

What's the best term for this 'style guide' thing so that I can create a repo and make a documented start?

Why not "visual style" and "coding style". I dig the explicitness.

[rjmk]

@FilWisher let a thousand standards bloom : https://github.com/JedWatson/happiness

@iteles What does 'fully commented code' mean? :worried: I find comments tend to reduce readability, but have certainly struggled through code where a comment or two would have been immensely helpful.

[iteles]

@FilWisher I take your point and I tend to agree, but I'm also curious about whether looking at a few of the visual pieces by default will give developers who focus exclusively on backend tasks a better view of how everything works together :wink: Also, "visual style" and "coding style" are perfect, thanks! :+1: :+1:

@rjmk Great point. I agree that that needs more explanation. We'll have a few examples, but it's mostly common sense, putting yourself in the shoes of the person who has to inherit your code. Usually whoever is QA'ing your code can help with this perspective (if they're good) - if they're asking 'what does this bit of your code do?' then you probably need a comment.

[iteles]

Adding some screenshots for the guide.

I actually think that we should have a 'set up your environment' guide separately so we don't pollute the styleguide with teaching people how to set up soft tabs... Thoughts anyone?

[nelsonic]

@iteles agreed. :+1:

[iteles]

I'm closing this issue for now as the style guide is an ongoing piece of work. All style guide issues can now be raised here :arrow_right: https://github.com/dwyl/style-guide