可调试性

This chapter contains considerations about debuggability.

Always provide a toString() method

To make debugging easier, add a toString() implementation to every class you introduce, even to internal ones. If toString() is part of a contract, document it explicitly.

The following code is a simplified example from a graphical modeling area:

  1. class Vector2D(val x: Int, val y: Int)
  2. fun main() {
  3. val result = (1..20).map { Vector2D(it, it) }
  4. println(result)
  5. }

The output of this code is not very useful:

  1. [Vector2D@27bc2616, Vector2D@3941a79c, Vector2D@506e1b77,...]

Neither is the information provided in the debug tool window:

Vector class objects in the debug tool window

To make both logging and debugging much more readable, add a simple toString() implementation like this:

  1. override fun toString(): String =
  2. "Vector2D(x=$x, y=$y)"

This results in improved output:

  1. [Vector2D(x=1, y=1), Vector2D(x=2, y=2), Vector2D(x=3, y=3), ...

Improved output of vector class objects in the debug tool window

It might seem like a good idea to use data classes because they have a toString() method automatically. In the Backward compatibility section of this guide, you’ll learn why it’s better not to do this.

可调试性 - 图3

Consider implementing toString() even if you don’t think the class is going to be printed anywhere, as it can help in unexpected ways. For example, inside builders, it may be important to see the current state of the builder.

  1. class Person(
  2. val name: String?,
  3. val age: Int?,
  4. val children: List<Person>
  5. ) {
  6. override fun toString(): String =
  7. "Person(name=$name, age=$age, children=$children)"
  8. }
  9. class PersonBuilder {
  10. var name: String? = null
  11. var age: Int? = null
  12. val children = arrayListOf<Person>()
  13. fun child(personBuilder: PersonBuilder.() -> Unit = {}) {
  14. children.add(person(personBuilder))
  15. }
  16. }
  17. fun person(personBuilder: PersonBuilder.() -> Unit = {}): Person {
  18. val builder = PersonBuilder()
  19. builder.personBuilder()
  20. return Person(builder.name, builder.age, builder.children)
  21. }

The intended use of the code above is the following:

Usage of the person DSL and a breakpoint

If you set a breakpoint on the line after the closing brace of the first child (as on the picture above), you see a non-descriptive string in debug output:

Result of a PersonBuilder debugging

If you add a simple toString() implementation like this:

  1. override fun toString(): String =
  2. "PersonBuilder(name=$name, age=$age, children=$children)"

The debug data becomes much clearer:

Result of a PersonBuilder improved debugging

You can also see immediately which fields are set and which are not.

Be careful with exposing fields in toString() because it might be easy to get a StackOverflowException. For example, if children has a reference to a parent, that would create a circular reference. Also, be careful about exposing lists and maps, as toString() can expand a deeply nested hierarchy.

{type = “warning”}

What’s next?

Learn about APIs’ backward compatibility.