├── img ├── figure-1.png ├── figure-2.png └── figure-3.png ├── .gitattributes ├── .gitignore ├── .editorconfig └── README.md /img/figure-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Alhadis/Coding-Style/HEAD/img/figure-1.png -------------------------------------------------------------------------------- /img/figure-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Alhadis/Coding-Style/HEAD/img/figure-2.png -------------------------------------------------------------------------------- /img/figure-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Alhadis/Coding-Style/HEAD/img/figure-3.png -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Include markdown in repository's language-stats 2 | *.md linguist-detectable=true 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | ## Mac OS/X 2 | .apdisk 3 | .AppleDB 4 | .AppleDesktop 5 | .AppleDouble 6 | .DS_Store 7 | .LSOverride 8 | ._* 9 | 10 | 11 | ## IDE-specific 12 | sftp-config.json 13 | .project 14 | 15 | 16 | ## Windows 17 | Desktop.ini 18 | Thumbs.db 19 | ehthumbs.db 20 | $RECYCLE.BIN/ 21 | *.lnk 22 | 23 | 24 | ## Other 25 | error_log 26 | node_modules 27 | components 28 | npm-debug.log 29 | .apl.history 30 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = tab 5 | charset = utf-8 6 | end_of_line = lf 7 | insert_final_newline = true 8 | trim_trailing_whitespace = false 9 | quote_type = double 10 | curly_bracket_next_line = false 11 | spaces_around_operators = false 12 | spaces_around_brackets = none 13 | indent_brace_style = K&R 14 | 15 | [{COMMIT_EDITMSG,MERGE_MSG}] 16 | trim_trailing_whitespace = true 17 | max_line_length = 72 18 | indent_style = space 19 | indent_size = 4 20 | 21 | [*.{cl,el,emacs,lisp,lsp,scm}] 22 | trim_trailing_whitespace = true 23 | indent_style = space 24 | indent_size = 2 25 | 26 | [*.{bat,cmd}] 27 | end_of_line = crlf 28 | 29 | [*.{clang-format,yml,yaml}] 30 | indent_style = space 31 | indent_size = 4 32 | 33 | [*.srt] 34 | charset = utf-8-bom 35 | end_of_line = crlf 36 | insert_final_newline = unset 37 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | You have open before you an unavoidably arrogant avalanche of bikeshedding which 2 | serves as an explanation of my personal coding style. While I don't envision any 3 | of my projects ever becoming a conduit for collaboration (since I prefer working 4 | alone), I'll at least have something in black-and-white to direct anybody to who 5 | feels compelled to send a PR on one of my projects. 6 | 7 | **~~Table~~** 8 | **TL;DR of contents:** 9 | 10 | 1. [Use tabs for indentation](#1-use-tabs-for-indentation) 11 | 2. [Don't use tabs for alignment](#2-dont-use-tabs-for-alignment) 12 | 3. [K&R bracing style](#3-bracing-style) 13 | 4. [Casing style](#4-casing-style) 14 | 5. [Use semicolons](#5-semicolons) 15 | 6. [Double-quotes](#6-double-quotes) 16 | 7. [Comma-last](#7-comma-last) 17 | 8. [Writing commit messages](#8-writing-commit-messages) 18 | 9. [No emoji](#9-no-emoji) 19 | 10. [No commit prefixes](#10-no-commit-prefixes) 20 | 11. [Line length](#11-line-length) 21 | 12. [Use standard English](#12-use-traditional-english-spelling-british-english) 22 | 13. [Conclusion](#conclusion) 23 | 24 | Let's get this shed painted. 25 | 26 | 27 | 1․ Use tabs for indentation 28 | -------------------------------------------------------------------------------- 29 | Use hard tabs `(U+0009)` to indent. 30 | 31 | If you prefer spaces for indentation, I'm automatically inclined to dislike you. 32 | Really, I'm not joking. I wish I were, as it'd imply I DON'T get eye strain when 33 | I try squinting through cramped columns of 2-space-indented JavaScript that kids 34 | these days seem to think is trendy (and some adults for some reason). 35 | 36 | ![Proud to detest the so-called JavaScript "Standard" Style](img/figure-1.png) 37 | 38 | Everybody has their own preference on what they're most comfortable reading. Let 39 | them enjoy it, use tabs, and *use them responsibly*. Which brings me to point 2: 40 | 41 | 42 | 2․ Don't use tabs for alignment 43 | -------------------------------------------------------------------------------- 44 | Never assume a tab will be of any particular length, even if your project has an 45 | `.editorconfig` file. Imagine a tab is an invisible, elastic region of space the 46 | coder can fluidly adjust to control their code's layout. Which it is. 47 | 48 | Use spaces for cosmetic alignment. Don't let them touch leading tabulation - tab 49 | characters should *never* come after a non-whitespace character (unless it's TSV 50 | data, but obviously that's a given). 51 | 52 | Avoid situations where it's tempting to use tabs as an alignment device: 53 | 54 | var a = "This is", 55 | b = "A common pattern", 56 | c = "in JavaScript"; 57 | 58 | I find this to be more readable: 59 | 60 | var a = "This is"; 61 | var b = "Slightly less"; 62 | var c = "Common in JavaScript"; 63 | 64 | I'm okay with the first notation, as long as it's used like this: 65 | 66 | var a = "This is", 67 | b = "Weird", 68 | c = "Right?"; 69 | 70 | If you're the comma-first sort of person (which I am *NOT*), you could do this: 71 | 72 | var a = "I hate" 73 | , b = "This form" 74 | , c = "Of notation." 75 | 76 | I think you get it. 77 | 78 | 79 | 3․ Bracing style 80 | -------------------------------------------------------------------------------- 81 | I prefer the K&R style, with curly-brackets only appearing on their own lines if 82 | the construct they're a part of can't be nested. For instance, in PHP, you can't 83 | have one class inside another, so this is fine: 84 | 85 | class Store 86 | { 87 | function query($args = array()){ 88 | 89 | } 90 | } 91 | 92 | Similarly, if it's a C project, the same logic applies to functions (which can't 93 | be nested): 94 | 95 | int main(int argc) 96 | { 97 | while(true){ 98 | printf("Piss off world, I'm working.\n"); 99 | return 1; 100 | } 101 | } 102 | 103 | I generally prefer no spaces between the closing bracket and the opening bracket 104 | (e.g., `function name(){`), but I won't bite your head off for inserting a space 105 | for readability. Unless of course, you're going around making wanton adjustments 106 | to existing code. If your PR's diffs crackle with noisy, irrelevant and cosmetic 107 | changes, it's getting kicked. 108 | 109 | 110 | 4․ Casing style 111 | -------------------------------------------------------------------------------- 112 | Depends on language. Stick to the style used by a language's standard library: 113 | 114 | * camelCase: JavaScript, Haskell 115 | * kebab-case: Anywhere where dashes are legal - HTML, CSS and filenames 116 | * snake_case: Anywhere where dashes *aren't* legal (PHP, Perl, most languages) 117 | 118 | Capitalisation follows the usual conventions of most programming languages: 119 | 120 | * Classes: PascalCase 121 | * Constants: SCREAMING_SNAKE_CASE 122 | * Anything else: lowerCase / lower-case / lower_case 123 | 124 | NOTE: My capitalisation of variable names is sometimes inconsistent when writing 125 | shell-scripts and Makefiles. Generally I'll start out writing them in UPPERCASE, 126 | then switch to lowercase when there're too many variables making everything look 127 | too shouty. 128 | 129 | 130 | 131 | 5․ Semicolons 132 | -------------------------------------------------------------------------------- 133 | Use them. They make unfamiliar code easier to skim through by showing where each 134 | statement terminates, distinguishing those split across multiple lines: 135 | 136 | let list = items 137 | .filter(a => a !== unwanted) 138 | .sort(a => a < b) 139 | .join(" ") 140 | .replace(/[A-Z]zip/g, "") 141 | .etc(); 142 | 143 | They're also not optional in every programming language. Trying to remember what 144 | languages have ASI and which don't is harder than simply hitting that damn extra 145 | key. And if that's too much effort for you, well, I imagine your emails probably 146 | look like this: 147 | 148 | > hey sup. i pushed a few comits last nite. 149 | > did you remember the question mark 150 | > what's the url 151 | 152 | 153 | 6․ Double-quotes 154 | -------------------------------------------------------------------------------- 155 | Use double-quotes, unless it's a language sensitive to interpolation (like shell 156 | scripts, Perl, or PHP). An exception is a string containing double-quotes of its 157 | own: if using single-quotes helps eliminate escape characters, use them instead: 158 | 159 | '"Use This"' 160 | "\"Not this\"" 161 | 162 | Because there's a difference between enforcing consistency and using your brain. 163 | It looks like this: 164 | 165 | "- \"" + name + "\": \"" + value + "\"" 166 | 167 | Instead of this: 168 | 169 | '- "' + name + '": ' + value + '"' 170 | 171 | That being said, don't quote keys in object literals if they don't need it: 172 | 173 | var obj = { 174 | "This needs it": 1, 175 | thisDoesNot: 1 176 | }; 177 | 178 | **Reason behind preference:** 179 | Double-quotes are easier to distinguish at a glance than apostrophes. Sure, they 180 | involve holding an extra key. Who cares? Get a better keyboard if pressing shift 181 | keys is too cumbersome for you. 182 | 183 | 184 | 7․ Comma-last 185 | -------------------------------------------------------------------------------- 186 | Nobody writes like this 187 | , so neither should you 188 | , unless you had one really 189 | , really 190 | , really 191 | , really 192 | , really weird education. 193 | 194 | But hey 195 | , less noise in your diffs 196 | , right? RIGHT? 197 | 198 | 199 | 200 | 8․ Writing commit messages 201 | -------------------------------------------------------------------------------- 202 | [This entire damn article](http://chris.beams.io/posts/git-commit/). Every point 203 | is like holy Git law to me. BE FOREWARNED: Not adhering to these points WILL get 204 | your PR rejected. The reason is simple: a commit message is permanent. Yes, it's 205 | possible to modify through rebasing, but that defeats the purpose of maintaining 206 | an honest and transparent modification history (and I'd rather not clobber a SHA 207 | hash just to amend the tone of a commit message). 208 | 209 | 210 | 211 | 9․ No emoji 212 | -------------------------------------------------------------------------------- 213 | GitHub like using cutesy graphics in their commit messages, and NPM do too, it'd 214 | seem. Submit a PR with an emoji *anywhere* and it'll get rejected - even if your 215 | code is nothing short of brilliant. 216 | 217 | Git isn't Twitter. What you're seeing on GitHub is only a decorated rendition of 218 | each commit's actual content: 219 | 220 | ![Figure 1](./img/figure-2.png) 221 | 222 | Although I guess it could always be worse: 223 | 224 | ![Figure 2](./img/figure-3.png) 225 | 226 | 227 | 228 | 10․ No commit prefixes 229 | -------------------------------------------------------------------------------- 230 | This ties in with the points raised in *"How to write a commit message"*, above. 231 | Use the imperative tone, leave out the leading `Prefix: Fix something`. Assuming 232 | you're clear, direct and informative with your subject lines, grepping through a 233 | `--oneline` log shouldn't be a hassle. 234 | 235 | 236 | 237 | 11․ Line length 238 | -------------------------------------------------------------------------------- 239 | 240 | * Commit subjects: <= 69 (REQUIRED) 241 | * Commit bodies: <= 72 (REQUIRED) 242 | * Prose or documentation: <~ 80 (Encouraged, but not mandatory) 243 | * Anything else/code: -- -- (Not fussed) 244 | 245 | I'm "not fussed" because none of my projects are expected to be worked on within 246 | width-challenged editing environments. If a future project is being written with 247 | utmost portability in mind (think ISO/Git-level), line length will be explicitly 248 | mentioned in `CONTRIBUTING.md`. 249 | 250 | Use your best judgement when determining how long is "too long". Things like big 251 | URLs and hairy regular expressions can't always be helped. They won't render the 252 | rest of the document unreadable if they're folded, either. Keeping documentation 253 | under a character limit is more a matter of keeping diffs more readable - a typo 254 | fix on a 450-character long line really doesn't make perusing a revision history 255 | very fun. 256 | 257 | (Anybody reading this file's source code should be advised that I DON'T expect a 258 | similar level of precision from contributions. That'd be kinda ridiculous). 259 | 260 | When keeping lines under a character limit, assume tabs to be 8-characters wide. 261 | This is the default size assumed by virtually all terminal-like environments: if 262 | somebody needs stuff kept within the 80-column boundary, you can probably assume 263 | they're using a TTY with 8-character tab-stops. Even if you're wrong, most users 264 | will have tab-sizes set to a smaller size like 4 or 2. Multics used 10-character 265 | tab-stops, but if that's an issue, please let me know. I want to be the first to 266 | try your time machine. 267 | 268 | 269 | 270 | 12․ Use traditional English spelling ("British" English) 271 | -------------------------------------------------------------------------------- 272 | Unsurprisingly, many open source projects suffer from an unpredictable mix of US 273 | English and traditional English (what the US call "British" English). I'm from a 274 | Commonwealth nation, and I was taught to use Standard English. Therefore, that's 275 | what I use when naming my identifiers (e.g., `class RGBColour`). I don't care if 276 | the language's standard library uses US English - my projects use the spelling I 277 | grew up with. And because I'm a pedantic prick, I'll enforce consistent language 278 | if I choose to. You mightn't like it. Tough shit. 279 | 280 | If writing "colour" bothers you, spare a thought for those of us forced to write 281 | "color" because a language was authored that way. Then imagine what it'd be like 282 | to feel that every day of your life while doing something you enjoy. 283 | 284 | 285 | 286 | Conclusion 287 | -------------------------------------------------------------------------------- 288 | I'm used to working alone - I write code for code's sake, not because I'd expect 289 | my projects to become group efforts. That doesn't mean I'm an arsehole: in fact, 290 | most people would describe me as goofy and eccentric. There aren't many things I 291 | take seriously, but code is one of them. Whether it's one of my own projects, or 292 | somebody else's, I do what any coder worth their salt is expected to do - honour 293 | the styleguide, and respect the decisions of the maintainers. 294 | 295 | Since I expect others will do the same, I've felt a rare moment of motivation to 296 | pen something that I've never otherwise put in writing. If my projects DO become 297 | group efforts one day (or become maintained posthumously), maintainers will have 298 | something substantial to go by. 299 | 300 | Otherwise, I don't expect anybody to think anything more of these self-important 301 | ramblings than any other styleguide they read and disagree with. Half the reason 302 | I wrote this was just an excuse to wrap shit to 80-characters without justifying 303 | text. Yeah, I love lining things up, who you gonna call? 304 | --------------------------------------------------------------------------------