Комментарии в цепочках звонков

Question

Поскольку при написании кода kotlin часто требуются более длинные цепочки вызовов, требующие объяснения.Что было бы лучшим местом для добавления комментариев в этой цепочке?

val map = javaClass.getResourceAsStream("/response.csv")
    .reader() //commentLocation1
    .readLines()
    .drop(1)
    // commentLocation2
    .map { it.split(",") }
    .map {
        // commentLocation3
        it.first().toInt() to it[2]
    }
    .toMap()

Answer 1

Я не нашел никаких подсказок по этому поводу в официальных соглашениях по кодированию , но я бы предпочел commentLocation1 и commentLocation3.Но помните, что предпочтительным способом выражения ваших намерений в коде является добавление функции с хорошим именем.Поэтому, если вы чувствуете, что необходимо добавить комментарий для описания бизнес-ценности некоторого отображения, фильтрации и т. Д., Лучше использовать ссылку на функцию, название которой объясняет это.

Answer 2

В общем, я считаю, что желание комментировать в середине цепочки является признаком того, что вы сделали вашу цепочку слишком длинной.Если вы разобьете его, вы можете использовать имена переменных, чтобы добавить немного «самодокументирования».

val responseReader = javaClass.getResourceAsStream("/response.csv").reader()
val linesWithoutHeader = responseReader.readLines().drop(1)
val splitLines = linesWithoutHeader.map{it.split(","))}
val map = splitLines.map(firstAndThirdColumns).toMap()
def firstAndThirdColumns(...

Это также дает преимущество, предоставляя вам более точное местоположение для сообщений об ошибках, ипозволяет вставлять аннотации типов, чтобы перепроверить что-то посередине.Когда кто-то поддерживает это позже, он может использовать имя промежуточной переменной вместо того, чтобы восстанавливать все состояние в своей голове с начала цепочки.И в худшем случае, если вы все еще чувствуете, что вам нужен комментарий, вы можете сделать его обычным построчным комментарием, который не выглядит так неловко.

Answer 3

Это всего лишь личное предпочтение, но мне не нравятся комментарии вне документов, ИМХО, это уменьшает вероятность сохранить устаревшие комментарии к коду, поэтому я рекомендую заключить код в функцию с любыми объяснениями, которые вы считаете необходимыми:

/**
 * This function does something very useful =)
 */
fun function(){

}