Depuis lors de l'écriture de code kotlin, il y a souvent des chaînes d'appels plus longues nécessitant des explications. Quel serait le meilleur endroit pour ajouter des commentaires dans cette chaîne?
val map = javaClass.getResourceAsStream("/response.csv")
.reader() //commentLocation1
.readLines()
.drop(1)
// commentLocation2
.map { it.split(",") }
.map {
// commentLocation3
it.first().toInt() to it[2]
}
.toMap()
3 Réponses :
C'est juste une préférence personnelle, mais je n'aime pas les commentaires en dehors de la documentation, à mon humble avis, cela réduit les chances de conserver les commentaires obsolètes sur le code, je recommande donc d'envelopper le code dans une fonction avec toutes les explications que vous jugez nécessaires:
/**
* This function does something very useful =)
*/
fun function(){
}
Je n'ai trouvé aucune indication à ce sujet dans les conventions de codage officielles , mais je préférerais commentLocation1 et commentLocation3. Mais rappelez-vous que la meilleure façon d'exprimer vos intentions dans le code est d'ajouter une fonction avec un bon nom. Donc, si vous pensez qu'il est nécessaire d'ajouter un commentaire pour la description de la valeur commerciale de certains mappages, filtrages, etc., il est préférable d'utiliser une référence à la fonction, dont le nom l'explique.
J'ai déjà vérifié les documents officiels de kotlin, et je n'ai pas non plus trouvé d'exemples sur des bibliothèques comme RxJava. Je vais probablement déplacer le code vers des fonctions et utiliser des références de fonction alors!
En général, je considère que vouloir faire un commentaire au milieu d'une chaîne est un signe que vous avez fait votre chaîne trop longue. Si vous le divisez, vous pouvez utiliser les noms de variables pour ajouter un peu d '"auto-documentation".
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(...
Cela a également l'avantage de vous donner un emplacement plus précis pour les messages d'erreur , et vous permet d'insérer des annotations de type pour vérifier quelque chose au milieu. Quand quelqu'un maintient cela plus tard, il peut être en mesure de sortir d'un nom de variable intermédiaire au lieu de reconstruire l'état entier dans sa tête depuis le début de la chaîne. Et le pire des cas, si vous sentez toujours que vous avez besoin d'un commentaire, vous pouvez en faire un commentaire de ligne régulier qui ne semble pas si gênant.