• Introduction
• Part 1 Good Code
  • Chapter 1 Safety
  • 引言
  • 第1条：限制可变性
  • 第2条：最小化变量作用域
  • 第3条：尽快消除平台类型
  • 第4条：不要把推断类型暴露给外部
  • Item 5 Specify Your Expectations On Arguments And State
  • 第6条：尽可能使用标准库中提供的异常
  • 第7条：当不能返回预期结果时，优先使用null o或Failure 作为返回值
  • Item 8 Handle Nulls Properly
  • 第9条：使用use关闭资源
  • Item 10 Write Unit Tests
  • Chapter 2 Readability
  • Introduction
  • Item 11 Design For Readability
  • Item 12 Operator Meaning Should Be Consistent With Its Function Name
  • Item 13 Avoid Returning Or Operating On Unit
  • Item 14 Specify The Variable Type When It Is Not Clear
  • Item 15 Consider Referencing Receivers Explicitly
  • Item 16 Properties Should Represent State Not Behavior
  • Item 17 Consider Naming Arguments
  • Item 18 Respect Coding Conventions
• Part 2 Code Design
  • Chapter 3 Reusability
  • Introduction
  • Item 19 Do Not Repeat Knowledge
  • Item 20 Do Not Repeat Common Algorithms
  • Item 21 Use Property Delegation To Extract Common Property Patterns
  • Item 22 Use Generics When Implementing Common Algorithms
  • Item 23 Avoid Shadowing Type Parameters
  • Item 24 Consider Variance For Generic Types
  • Item 25 Reuse Between Different Platforms By Extracting Common Modules
  • Chapter 4 Abstraction Design
  • Introduction
  • Item 26 Each Function Should Be Written In Terms Of A Single Level Of Abstraction
  • Item 27 Use Abstraction To Protect Code Against Changes
  • Item 28 Specify API Stability
  • Item 29 Consider Wrapping External API
  • Item 30 Minimize Elements Visibility
  • Item 31 Define Contract With Documentation
  • Item 32 Respect Abstraction Contracts
  • Chapter 5 Object Creation
  • Introduction
  • Item 33 Consider Factory Functions Instead Of Constructors
  • Item 34 Consider A Primary Constructor With Named Optional Arguments
  • Item 35 Consider Defining A DSL For Complex Object Creation
  • Chapter 6 Class Design
  • Introduction
  • Item 36 Prefer Composition Over Inheritance
  • Item 37 Use The Data Modifier To Represent A Bundle Of Data
  • Item 38 Use Function Types Instead Of Interfaces To Pass Operations And Actions
  • Item 39 Prefer Class Hierarchies To Tagged Classes
  • Item 40 Respect The Contract Of Equals
  • Item 41 Respect The Contract Of Hash Code
  • Item 42 Respect The Contract Of Compare To
  • Item 43 Consider Extracting Non Essential Parts Of Your API Into Extensions
  • Item 44 Avoid Member Extensions
• Part 3 Efficiency
  • Chapter 7 Make It Cheap
  • Introduction
  • Item 45 Avoid Unnecessary Object Creation
  • Item 46 Use Inline Modifier For Functions With Parameters Of Functional Types
  • Item 47 Consider Using Inline Classes
  • Item 48 Eliminate Obsolete Object References
  • Chapter 8 Efficient Collection Processing
  • Introduction
  • Item 49 Prefer Sequence For Big Collections With More Than One Processing Step
  • Item 50 Limit The Number Of Operations
  • Item 51 Consider Arrays With Primitives For Performance Critical Processing
  • Item 52 Consider Using Mutable Collections
• Published with GitBook

Item 18 Respect Coding Conventions

Item 18: Respect coding conventions

Kotlin has well-established coding conventions described in the documentation in a section aptly called “Coding Conventions”. Those conventions are not optimal for all projects, but it is optimal for us as a community to have conventions that are respected in all projects. Thanks to them:

• It is easier to switch between projects
• Code is more readable even for external developers
• It is easier to guess how code works
• It is easier to later merge code with a common repository or to move some parts of code from one project to another

Programmers should get familiar with those conventions as they are described in the documentation. They should also be respected when they change - which might happen to some degree over time. Since it is hard to do both, there are two tools that help:

• The IntelliJ formatter can be set up to automatically format according to the official Coding Conventions style. For that go to Settings | Editor | Code Style | Kotlin, click on “Set from…” link in the upper right corner, and select “Predefined style / Kotlin style guide” from the menu.
• ktlint - popular linter that analyzes your code and notifies you about all coding conventions violations.

Looking at Kotlin projects, I see that most of them are intuitively consistent with most of the conventions. This is probably because Kotlin mostly follows the Java coding conventions, and most Kotlin developers today are post-Java developers. One rule that I see often violated is how classes and functions should be formatted. According to the conventions, classes with a short primary-constructor can be defined in a single line:

class FullName(val name: String, val surname: String)

However, classes with many parameters should be formatted in a way so that every parameter is on another line, and there is no parameter in the first line:

class Person(
    val id: Int = 0,
    val name: String = "",
    val surname: String = ""
) : Human(id, name) { 
    // body
}

Similarly, this is how we format a long function:

public fun <T> Iterable<T>.joinToString(
    separator: CharSequence = ", ", 
    prefix: CharSequence = "", 
    postfix: CharSequence = "", 
    limit: Int = -1, 
    truncated: CharSequence = "...", 
    transform: ((T) -> CharSequence)? = null
): String {
   // ...
}

Notice that those two are very different from the convention that leaves the first parameter in the same line and then indents all others to it.

// Don’t do that
class Person(val id: Int = 0,
             val name: String = "",
             val surname: String = "") : Human(id, name){ 
    // body
}

It can be problematic in 2 ways:

• Arguments on every class start with a different indentation based on the class name. Also, when we change the class name, we need to adjust the indentations of all primary constructor parameters.
• Classes defined this way tend to be still too wide. Width of the class defined this way is the class name with class keyword and the longest primary constructor parameter, or last parameter plus superclasses and interfaces.

Some teams might decide to use slightly different conventions. This is fine, but then those conventions should be respected all around the given project. Every project should look like it was written by a single person, not a group of people fighting with each other.

Coding conventions are often not respected enough by developers, but they are important, and a chapter dedicated to readability in a best practices book couldn’t be closed without at least a short section dedicated to them. Read them, use static checkers to help you be consistent with them, apply them in your projects. By respecting coding conventions, we make Kotlin projects better for us all.

results matching ""

No results matching ""