https://github.com/alhadis/coding-style
Personal coding preferences I hope everybody reads.
https://github.com/alhadis/coding-style
indentation semantic-formatting styleguide styleguide-javascript tabs
Last synced: 2 months ago
JSON representation
Personal coding preferences I hope everybody reads.
- Host: GitHub
- URL: https://github.com/alhadis/coding-style
- Owner: Alhadis
- Created: 2016-03-18T17:22:04.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2021-10-01T14:27:03.000Z (over 3 years ago)
- Last Synced: 2025-01-25T06:41:54.444Z (4 months ago)
- Topics: indentation, semantic-formatting, styleguide, styleguide-javascript, tabs
- Homepage:
- Size: 497 KB
- Stars: 13
- Watchers: 6
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
You have open before you an unavoidably arrogant avalanche of bikeshedding which
serves as an explanation of my personal coding style. While I don't envision any
of my projects ever becoming a conduit for collaboration (since I prefer working
alone), I'll at least have something in black-and-white to direct anybody to who
feels compelled to send a PR on one of my projects.
**~~Table~~**
**TL;DR of contents:**
1. [Use tabs for indentation](#1-use-tabs-for-indentation)
2. [Don't use tabs for alignment](#2-dont-use-tabs-for-alignment)
3. [K&R bracing style](#3-bracing-style)
4. [Casing style](#4-casing-style)
5. [Use semicolons](#5-semicolons)
6. [Double-quotes](#6-double-quotes)
7. [Comma-last](#7-comma-last)
8. [Writing commit messages](#8-writing-commit-messages)
9. [No emoji](#9-no-emoji)
10. [No commit prefixes](#10-no-commit-prefixes)
11. [Line length](#11-line-length)
12. [Use standard English](#12-use-traditional-english-spelling-british-english)
13. [Conclusion](#conclusion)
Let's get this shed painted.
1․ Use tabs for indentation
--------------------------------------------------------------------------------
Use hard tabs `(U+0009)` to indent.
If you prefer spaces for indentation, I'm automatically inclined to dislike you.
Really, I'm not joking. I wish I were, as it'd imply I DON'T get eye strain when
I try squinting through cramped columns of 2-space-indented JavaScript that kids
these days seem to think is trendy (and some adults for some reason).
Everybody has their own preference on what they're most comfortable reading. Let
them enjoy it, use tabs, and *use them responsibly*. Which brings me to point 2:
2․ Don't use tabs for alignment
--------------------------------------------------------------------------------
Never assume a tab will be of any particular length, even if your project has an
`.editorconfig` file. Imagine a tab is an invisible, elastic region of space the
coder can fluidly adjust to control their code's layout. Which it is.
Use spaces for cosmetic alignment. Don't let them touch leading tabulation - tab
characters should *never* come after a non-whitespace character (unless it's TSV
data, but obviously that's a given).
Avoid situations where it's tempting to use tabs as an alignment device:
var a = "This is",
b = "A common pattern",
c = "in JavaScript";
I find this to be more readable:
var a = "This is";
var b = "Slightly less";
var c = "Common in JavaScript";
I'm okay with the first notation, as long as it's used like this:
var a = "This is",
b = "Weird",
c = "Right?";
If you're the comma-first sort of person (which I am *NOT*), you could do this:
var a = "I hate"
, b = "This form"
, c = "Of notation."
I think you get it.
3․ Bracing style
--------------------------------------------------------------------------------
I prefer the K&R style, with curly-brackets only appearing on their own lines if
the construct they're a part of can't be nested. For instance, in PHP, you can't
have one class inside another, so this is fine:
class Store
{
function query($args = array()){
}
}
Similarly, if it's a C project, the same logic applies to functions (which can't
be nested):
int main(int argc)
{
while(true){
printf("Piss off world, I'm working.\n");
return 1;
}
}
I generally prefer no spaces between the closing bracket and the opening bracket
(e.g., `function name(){`), but I won't bite your head off for inserting a space
for readability. Unless of course, you're going around making wanton adjustments
to existing code. If your PR's diffs crackle with noisy, irrelevant and cosmetic
changes, it's getting kicked.
4․ Casing style
--------------------------------------------------------------------------------
Depends on language. Stick to the style used by a language's standard library:
* camelCase: JavaScript, Haskell
* kebab-case: Anywhere where dashes are legal - HTML, CSS and filenames
* snake_case: Anywhere where dashes *aren't* legal (PHP, Perl, most languages)
Capitalisation follows the usual conventions of most programming languages:
* Classes: PascalCase
* Constants: SCREAMING_SNAKE_CASE
* Anything else: lowerCase / lower-case / lower_case
NOTE: My capitalisation of variable names is sometimes inconsistent when writing
shell-scripts and Makefiles. Generally I'll start out writing them in UPPERCASE,
then switch to lowercase when there're too many variables making everything look
too shouty.
5․ Semicolons
--------------------------------------------------------------------------------
Use them. They make unfamiliar code easier to skim through by showing where each
statement terminates, distinguishing those split across multiple lines:
let list = items
.filter(a => a !== unwanted)
.sort(a => a < b)
.join(" ")
.replace(/[A-Z]zip/g, "")
.etc();
They're also not optional in every programming language. Trying to remember what
languages have ASI and which don't is harder than simply hitting that damn extra
key. And if that's too much effort for you, well, I imagine your emails probably
look like this:
> hey sup. i pushed a few comits last nite.
> did you remember the question mark
> what's the url
6․ Double-quotes
--------------------------------------------------------------------------------
Use double-quotes, unless it's a language sensitive to interpolation (like shell
scripts, Perl, or PHP). An exception is a string containing double-quotes of its
own: if using single-quotes helps eliminate escape characters, use them instead:
'"Use This"'
"\"Not this\""
Because there's a difference between enforcing consistency and using your brain.
It looks like this:
"- \"" + name + "\": \"" + value + "\""
Instead of this:
'- "' + name + '": ' + value + '"'
That being said, don't quote keys in object literals if they don't need it:
var obj = {
"This needs it": 1,
thisDoesNot: 1
};
**Reason behind preference:**
Double-quotes are easier to distinguish at a glance than apostrophes. Sure, they
involve holding an extra key. Who cares? Get a better keyboard if pressing shift
keys is too cumbersome for you.
7․ Comma-last
--------------------------------------------------------------------------------
Nobody writes like this
, so neither should you
, unless you had one really
, really
, really
, really
, really weird education.
But hey
, less noise in your diffs
, right? RIGHT?
8․ Writing commit messages
--------------------------------------------------------------------------------
[This entire damn article](http://chris.beams.io/posts/git-commit/). Every point
is like holy Git law to me. BE FOREWARNED: Not adhering to these points WILL get
your PR rejected. The reason is simple: a commit message is permanent. Yes, it's
possible to modify through rebasing, but that defeats the purpose of maintaining
an honest and transparent modification history (and I'd rather not clobber a SHA
hash just to amend the tone of a commit message).
9․ No emoji
--------------------------------------------------------------------------------
GitHub like using cutesy graphics in their commit messages, and NPM do too, it'd
seem. Submit a PR with an emoji *anywhere* and it'll get rejected - even if your
code is nothing short of brilliant.
Git isn't Twitter. What you're seeing on GitHub is only a decorated rendition of
each commit's actual content:
Although I guess it could always be worse:
10․ No commit prefixes
--------------------------------------------------------------------------------
This ties in with the points raised in *"How to write a commit message"*, above.
Use the imperative tone, leave out the leading `Prefix: Fix something`. Assuming
you're clear, direct and informative with your subject lines, grepping through a
`--oneline` log shouldn't be a hassle.
11․ Line length
--------------------------------------------------------------------------------
* Commit subjects: <= 69 (REQUIRED)
* Commit bodies: <= 72 (REQUIRED)
* Prose or documentation: <~ 80 (Encouraged, but not mandatory)
* Anything else/code: -- -- (Not fussed)
I'm "not fussed" because none of my projects are expected to be worked on within
width-challenged editing environments. If a future project is being written with
utmost portability in mind (think ISO/Git-level), line length will be explicitly
mentioned in `CONTRIBUTING.md`.
Use your best judgement when determining how long is "too long". Things like big
URLs and hairy regular expressions can't always be helped. They won't render the
rest of the document unreadable if they're folded, either. Keeping documentation
under a character limit is more a matter of keeping diffs more readable - a typo
fix on a 450-character long line really doesn't make perusing a revision history
very fun.
(Anybody reading this file's source code should be advised that I DON'T expect a
similar level of precision from contributions. That'd be kinda ridiculous).
When keeping lines under a character limit, assume tabs to be 8-characters wide.
This is the default size assumed by virtually all terminal-like environments: if
somebody needs stuff kept within the 80-column boundary, you can probably assume
they're using a TTY with 8-character tab-stops. Even if you're wrong, most users
will have tab-sizes set to a smaller size like 4 or 2. Multics used 10-character
tab-stops, but if that's an issue, please let me know. I want to be the first to
try your time machine.
12․ Use traditional English spelling ("British" English)
--------------------------------------------------------------------------------
Unsurprisingly, many open source projects suffer from an unpredictable mix of US
English and traditional English (what the US call "British" English). I'm from a
Commonwealth nation, and I was taught to use Standard English. Therefore, that's
what I use when naming my identifiers (e.g., `class RGBColour`). I don't care if
the language's standard library uses US English - my projects use the spelling I
grew up with. And because I'm a pedantic prick, I'll enforce consistent language
if I choose to. You mightn't like it. Tough shit.
If writing "colour" bothers you, spare a thought for those of us forced to write
"color" because a language was authored that way. Then imagine what it'd be like
to feel that every day of your life while doing something you enjoy.
Conclusion
--------------------------------------------------------------------------------
I'm used to working alone - I write code for code's sake, not because I'd expect
my projects to become group efforts. That doesn't mean I'm an arsehole: in fact,
most people would describe me as goofy and eccentric. There aren't many things I
take seriously, but code is one of them. Whether it's one of my own projects, or
somebody else's, I do what any coder worth their salt is expected to do - honour
the styleguide, and respect the decisions of the maintainers.
Since I expect others will do the same, I've felt a rare moment of motivation to
pen something that I've never otherwise put in writing. If my projects DO become
group efforts one day (or become maintained posthumously), maintainers will have
something substantial to go by.
Otherwise, I don't expect anybody to think anything more of these self-important
ramblings than any other styleguide they read and disagree with. Half the reason
I wrote this was just an excuse to wrap shit to 80-characters without justifying
text. Yeah, I love lining things up, who you gonna call?