├── README.md └── settings.jar /README.md: -------------------------------------------------------------------------------- 1 | # The Official Kodeco Kotlin Style Guide 2 | 3 | This style guide is different from others you may see, because the focus is centered on readability for print and the web. We created this style guide to keep the code in our tutorials consistent. 4 | 5 | Our overarching goals are __conciseness__, __readability__ and __simplicity__. 6 | 7 | You should also check out our other style guides: 8 | 9 | * [Swift](https://github.com/kodecocodes/swift-style-guide) 10 | * [Objective-C](https://github.com/kodecocodes/objective-c-style-guide) 11 | * [Java](https://github.com/kodecocodes/java-style-guide) 12 | 13 | ## Inspiration 14 | 15 | This style-guide is somewhat of a mash-up between the existing Kotlin language style guides, and a tutorial-readability focused Swift style-guide. The language guidance is drawn from: 16 | 17 | - The [Android Kotlin style guide](https://android.github.io/kotlin-guides/style.html) 18 | - The [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html) 19 | - The [Android contributors style guide](https://source.android.com/source/code-style.html) 20 | - The [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). 21 | 22 | Alterations to support additional readability in tutorials were inspired by the [Kodeco Swift style guide](https://github.com/kodecocodes/swift-style-guide). 23 | 24 | ## Android Studio Coding Style 25 | 26 | It is possible to get Android Studio to adhere to these style guidelines, via a rather complex sequence of menus. To make it easier, we've provided a coding style that can be imported into Android Studio. 27 | 28 | The file can be found [here](https://koenig-media.raywenderlich.com/uploads/2018/03/rwstyle.xml_.zip). 29 | 30 | To install the file, open Android Studio Settings and go to **Editor > Code Style > Kotlin**, then click the gear menu and choose **Import Scheme...**. 31 | 32 | From now on, projects you create _should_ follow the correct style guidelines. 33 | 34 | 35 | ## Table of Contents 36 | 37 | - [Nomenclature](#nomenclature) 38 | + [Packages](#packages) 39 | + [Classes & Interfaces](#classes--interfaces) 40 | + [Methods](#methods) 41 | + [Fields](#fields) 42 | + [Variables & Parameters](#variables--parameters) 43 | + [Misc](#misc) 44 | - [Declarations](#declarations) 45 | + [Visibility Modifiers](#visibility-modifiers) 46 | + [Fields & Variables](#fields--variables) 47 | + [Classes](#classes) 48 | + [Data Type Objects](#data-type-objects) 49 | + [Enum Classes](#enum-classes) 50 | - [Spacing](#spacing) 51 | + [Indentation](#indentation) 52 | + [Line Length](#line-length) 53 | + [Vertical Spacing](#vertical-spacing) 54 | - [Semicolons](#semicolons) 55 | - [Getters & Setters](#getters--setters) 56 | - [Brace Style](#brace-style) 57 | - [When Statements](#when-statements) 58 | - [Annotations](#annotations) 59 | - [Types](#types) 60 | + [Type Inference](#type-inference) 61 | + [Constants vs. Variables](#constants-vs-variables) 62 | + [Optionals](#optionals) 63 | - [XML Guidance](#xml-guidance) 64 | - [Language](#language) 65 | - [Copyright Statement](#copyright-statement) 66 | - [Smiley Face](#smiley-face) 67 | - [Credit](#credits) 68 | 69 | 70 | ## Nomenclature 71 | 72 | On the whole, naming should follow Java standards, as Kotlin is a JVM-compatible language. 73 | 74 | ### Packages 75 | 76 | Package names are similar to Java: all __lower-case__, multiple words concatenated together, without hypens or underscores: 77 | 78 | __BAD__: 79 | 80 | ```kotlin 81 | com.YourCompany.funky_widget 82 | ``` 83 | 84 | __GOOD__: 85 | 86 | ```kotlin 87 | com.yourcompany.funkywidget 88 | ``` 89 | 90 | ### Classes & Interfaces 91 | 92 | Written in __UpperCamelCase__. For example `RadialSlider`. 93 | 94 | ### Methods 95 | 96 | Written in __lowerCamelCase__. For example `setValue`. 97 | 98 | ### Fields 99 | 100 | Generally, written in __lowerCamelCase__. Fields should **not** be named with Hungarian notation, as Hungarian notation is [erroneously thought](http://jakewharton.com/just-say-no-to-hungarian-notation/) to be recommended by Google. 101 | 102 | Example field names: 103 | 104 | ```kotlin 105 | class MyClass { 106 | var publicField: Int = 0 107 | val person = Person() 108 | private var privateField: Int? 109 | } 110 | ``` 111 | 112 | Constant values in the companion object should be written in __uppercase__, with an underscore separating words: 113 | 114 | ```kotlin 115 | companion object { 116 | const val THE_ANSWER = 42 117 | } 118 | ``` 119 | 120 | ### Variables & Parameters 121 | 122 | Written in __lowerCamelCase__. 123 | 124 | Single character values must be avoided, except for temporary looping variables. 125 | 126 | ### Misc 127 | 128 | In code, acronyms should be treated as words. For example: 129 | 130 | __BAD:__ 131 | 132 | ```kotlin 133 | XMLHTTPRequest 134 | URL: String? 135 | findPostByID 136 | ``` 137 | __GOOD:__ 138 | 139 | ```kotlin 140 | XmlHttpRequest 141 | url: String 142 | findPostById 143 | ``` 144 | 145 | ## Declarations 146 | 147 | ### Visibility Modifiers 148 | 149 | Only include visibility modifiers if you need something other than the default of public. 150 | 151 | **BAD:** 152 | 153 | ```kotlin 154 | public val wideOpenProperty = 1 155 | private val myOwnPrivateProperty = "private" 156 | ``` 157 | 158 | **GOOD:** 159 | 160 | ```kotlin 161 | val wideOpenProperty = 1 162 | private val myOwnPrivateProperty = "private" 163 | ``` 164 | 165 | ### Access Level Modifiers 166 | 167 | Access level modifiers should be explicitly defined for classes, methods and member variables. 168 | 169 | ### Fields & Variables 170 | 171 | Prefer single declaration per line. 172 | 173 | __GOOD:__ 174 | 175 | ```kotlin 176 | username: String 177 | twitterHandle: String 178 | ``` 179 | 180 | ### Classes 181 | 182 | Exactly one class per source file, although inner classes are encouraged where scoping appropriate. 183 | 184 | ### Data Type Objects 185 | 186 | Prefer data classes for simple data holding objects. 187 | 188 | __BAD:__ 189 | 190 | ```kotlin 191 | class Person(val name: String) { 192 | override fun toString() : String { 193 | return "Person(name=$name)" 194 | } 195 | } 196 | ``` 197 | 198 | __GOOD:__ 199 | 200 | ```kotlin 201 | data class Person(val name: String) 202 | ``` 203 | 204 | ### Enum Classes 205 | 206 | Enum classes without methods may be formatted without line-breaks, as follows: 207 | 208 | ```kotlin 209 | private enum CompassDirection { EAST, NORTH, WEST, SOUTH } 210 | ``` 211 | 212 | ## Spacing 213 | 214 | Spacing is especially important in Kodeco code, as code needs to be easily readable as part of the tutorial. 215 | 216 | ### Indentation 217 | 218 | Indentation is using spaces - never tabs. 219 | 220 | #### Blocks 221 | 222 | Indentation for blocks uses 2 spaces (not the default 4): 223 | 224 | __BAD:__ 225 | 226 | ```kotlin 227 | for (i in 0..9) { 228 | Log.i(TAG, "index=" + i) 229 | } 230 | ``` 231 | 232 | __GOOD:__ 233 | 234 | ```kotlin 235 | for (i in 0..9) { 236 | Log.i(TAG, "index=" + i) 237 | } 238 | ``` 239 | 240 | #### Line Wraps 241 | 242 | Indentation for line wraps should use 4 spaces (not the default 8): 243 | 244 | __BAD:__ 245 | 246 | ```kotlin 247 | val widget: CoolUiWidget = 248 | someIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line) 249 | ``` 250 | 251 | __GOOD:__ 252 | 253 | ```kotlin 254 | val widget: CoolUiWidget = 255 | someIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line) 256 | ``` 257 | 258 | ### Line Length 259 | 260 | Lines should be no longer than 100 characters long. 261 | 262 | 263 | ### Vertical Spacing 264 | 265 | There should be exactly one blank line between methods to aid in visual clarity and organization. Whitespace within methods should separate functionality, but having too many sections in a method often means you should refactor into several methods. 266 | 267 | ## Comments 268 | 269 | When they are needed, use comments to explain **why** a particular piece of code does something. Comments must be kept up-to-date or deleted. 270 | 271 | Avoid block comments inline with code, as the code should be as self-documenting as possible. *Exception: This does not apply to those comments used to generate documentation.* 272 | 273 | 274 | ## Semicolons 275 | 276 | Semicolons ~~are dead to us~~ should be avoided wherever possible in Kotlin. 277 | 278 | __BAD__: 279 | 280 | ```kotlin 281 | val horseGiftedByTrojans = true; 282 | if (horseGiftedByTrojans) { 283 | bringHorseIntoWalledCity(); 284 | } 285 | ``` 286 | 287 | __GOOD__: 288 | 289 | ```kotlin 290 | val horseGiftedByTrojans = true 291 | if (horseGiftedByTrojans) { 292 | bringHorseIntoWalledCity() 293 | } 294 | ``` 295 | 296 | ## Getters & Setters 297 | 298 | Unlike Java, direct access to fields in Kotlin is preferred. 299 | 300 | If custom getters and setters are required, they should be declared [following Kotlin conventions](https://kotlinlang.org/docs/reference/properties.html) rather than as separate methods. 301 | 302 | ## Brace Style 303 | 304 | Only trailing closing-braces are awarded their own line. All others appear the same line as preceding code: 305 | 306 | __BAD:__ 307 | 308 | ```kotlin 309 | class MyClass 310 | { 311 | fun doSomething() 312 | { 313 | if (someTest) 314 | { 315 | // ... 316 | } 317 | else 318 | { 319 | // ... 320 | } 321 | } 322 | } 323 | ``` 324 | 325 | __GOOD:__ 326 | 327 | ```kotlin 328 | class MyClass { 329 | fun doSomething() { 330 | if (someTest) { 331 | // ... 332 | } else { 333 | // ... 334 | } 335 | } 336 | } 337 | ``` 338 | 339 | Conditional statements are always required to be enclosed with braces, irrespective of the number of lines required. 340 | 341 | __BAD:__ 342 | 343 | ```kotlin 344 | if (someTest) 345 | doSomething() 346 | if (someTest) doSomethingElse() 347 | ``` 348 | 349 | __GOOD:__ 350 | 351 | ```kotlin 352 | if (someTest) { 353 | doSomething() 354 | } 355 | if (someTest) { doSomethingElse() } 356 | ``` 357 | 358 | ## When Statements 359 | 360 | Unlike `switch` statements in Java, `when` statements do not fall through. Separate cases using commas if they should be handled the same way. Always include the else case. 361 | 362 | __BAD:__ 363 | 364 | ```kotlin 365 | when (anInput) { 366 | 1 -> doSomethingForCaseOneOrTwo() 367 | 2 -> doSomethingForCaseOneOrTwo() 368 | 3 -> doSomethingForCaseThree() 369 | } 370 | ``` 371 | 372 | __GOOD:__ 373 | 374 | ```kotlin 375 | when (anInput) { 376 | 1, 2 -> doSomethingForCaseOneOrTwo() 377 | 3 -> doSomethingForCaseThree() 378 | else -> println("No case satisfied") 379 | } 380 | ``` 381 | 382 | 383 | ## Types 384 | 385 | Always use Kotlin's native types when available. Kotlin is JVM-compatible so **[TODO: more info]** 386 | 387 | ### Type Inference 388 | 389 | Type inference should be preferred where possible to explicitly declared types. 390 | 391 | __BAD:__ 392 | 393 | ```kotlin 394 | val something: MyType = MyType() 395 | val meaningOfLife: Int = 42 396 | ``` 397 | 398 | __GOOD:__ 399 | 400 | ```kotlin 401 | val something = MyType() 402 | val meaningOfLife = 42 403 | ``` 404 | 405 | ### Constants vs. Variables 406 | 407 | Constants are defined using the `val` keyword, and variables with the `var` keyword. Always use `val` instead of `var` if the value of the variable will not change. 408 | 409 | *Tip*: A good technique is to define everything using `val` and only change it to `var` if the compiler complains! 410 | 411 | ### Nullable Types 412 | 413 | Declare variables and function return types as nullable with `?` where a `null` value is acceptable. 414 | 415 | Use implicitly unwrapped types declared with `!!` only for instance variables that you know will be initialized before use, such as subviews that will be set up in `onCreate` for an Activity or `onCreateView` for a Fragment. 416 | 417 | When naming nullable variables and parameters, avoid naming them like `nullableString` or `maybeView` since their nullability is already in the type declaration. 418 | 419 | When accessing a nullable value, use the safe call operator if the value is only accessed once or if there are many nullables in the chain: 420 | 421 | ```kotlin 422 | editText?.setText("foo") 423 | ``` 424 | 425 | 426 | 427 | ## XML Guidance 428 | 429 | Since Android uses XML extensively in addition to Kotlin and Java, we have some rules specific to XML. These can be found in our [Java code standards](https://github.com/kodecocodes/java-style-guide#xml-guidance) 430 | 431 | 432 | ## Language 433 | 434 | Use `en-US` English spelling. 🇺🇸 435 | 436 | __BAD:__ 437 | 438 | ```kotlin 439 | val colourName = "red" 440 | ``` 441 | 442 | __GOOD:__ 443 | 444 | ```kotlin 445 | val colorName = "red" 446 | ``` 447 | 448 | ## Copyright Statement 449 | 450 | The following copyright statement should be included at the top of every source file: 451 | 452 | ``` 453 | /* 454 | * Copyright (c) 2023 Kodeco Inc. 455 | * 456 | * Permission is hereby granted, free of charge, to any person obtaining a copy 457 | * of this software and associated documentation files (the "Software"), to deal 458 | * in the Software without restriction, including without limitation the rights 459 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 460 | * copies of the Software, and to permit persons to whom the Software is 461 | * furnished to do so, subject to the following conditions: 462 | * 463 | * The above copyright notice and this permission notice shall be included in 464 | * all copies or substantial portions of the Software. 465 | * 466 | * Notwithstanding the foregoing, you may not use, copy, modify, merge, publish, 467 | * distribute, sublicense, create a derivative work, and/or sell copies of the 468 | * Software in any work that is designed, intended, or marketed for pedagogical or 469 | * instructional purposes related to programming, coding, application development, 470 | * or information technology. Permission for such use, copying, modification, 471 | * merger, publication, distribution, sublicensing, creation of derivative works, 472 | * or sale is expressly withheld. 473 | * 474 | * This project and source code may use libraries or frameworks that are 475 | * released under various Open-Source licenses. Use of those libraries and 476 | * frameworks are governed by their own individual licenses. 477 | * 478 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 479 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 480 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 481 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 482 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 483 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 484 | * THE SOFTWARE. 485 | */ 486 | ``` 487 | 488 | ## Smiley Face 489 | 490 | Smiley faces are a very prominent style feature of the kodeco.com site! It is very important to have the correct smile signifying the immense amount of happiness and excitement for the coding topic. The closing square bracket ] is used because it represents the largest smile able to be captured using ASCII art. A closing parenthesis ) creates a half-hearted smile, and thus is not preferred. 491 | 492 | Bad: 493 | 494 | :) 495 | 496 | Good: 497 | 498 | :] 499 | 500 | ## Credits 501 | 502 | This style guide is a collaborative effort from the most stylish 503 | kodeco.com team members: 504 | 505 | - [Darryl Bayliss](https://github.com/DarrylBayliss) 506 | - [Tom Blankenship](https://github.com/tgblank) 507 | - [Sam Davies](https://github.com/sammyd) 508 | - [Mic Pringle](https://github.com/micpringle) 509 | - [Ellen Shapiro](https://github.com/designatednerd) 510 | - [Ray Wenderlich](https://github.com/rwenderlich) 511 | - [Joe Howard](https://github.com/orionthwake) 512 | -------------------------------------------------------------------------------- /settings.jar: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/kodecocodes/kotlin-style-guide/f965dd73e03e96e10b5fcf0e7ef4fa6914eba7ce/settings.jar --------------------------------------------------------------------------------