diktat

DIKTAT es un estricto estándar de codificación para Kotlin, que consiste en una colección de reglas de estilo de código Kotlin implementadas como visitantes de árbol de sintaxis abstracto (AST) construidos sobre Ktlint. Sirve el propósito de detectar y fijar automáticamente los olores de código en el proceso de integración continua/implementación continua (CI/CD). Puede encontrar la lista completa de reglas e inspecciones compatibles aquí.

Diktat ha ganado reconocimiento y se ha agregado a las listas de herramientas de análisis estático, Kotlin-Awesome y Kompar. ¡Extendemos nuestra gratitud a la comunidad por este apoyo!

Ver primero

Estilo de código	Inspección	Ejemplos	Manifestación	Papel blanco	Grupos de inspecciones

¿Por qué elegir Diktat para CI/CD?

Si bien hay otras herramientas como detekt y ktlint que realizan análisis estáticos, es posible que se pregunte por qué Diktat es necesario. Estas son las razones clave:

1. Más inspecciones: Diktat cuenta con más de 100 inspecciones estrechamente junto con su estilo CodeStyle.

2. Inspecciones únicas: Diktat presenta inspecciones únicas que no se encuentran en otras revestimientos.

3. Altamente configurable: cada inspección es altamente configurable, lo que permite la personalización y la supresión. Verifique las opciones de configuración y la supresión.

4. Strict CodeStyle: Diktat aplica un CodeStyle detallado que se puede adoptar y aplicar en su proyecto.

Ejecutar como aplicación cli

Descargar binario

1. Descargar Diktat manualmente: aquí

   O usar curl :

   curl -sSLO https://github.com/saveourtool/diktat/releases/download/v2.0.0/diktat && chmod a+x diktat

Solo para Windows . Descargue diktat.cmd manualmente: aquí

Correr diktat

Finalmente, ejecute Ktlint (con Diktat inyectado) para verificar sus archivos '*.kt' en 'dir/su/dir':

$ ./diktat " dir/your/dir/**/*.kt "

En Windows

 diktat.bat "dir/your/dir/**/*.kt"

Para autoifijo todas las violaciones de estilo de código, use la opción --mode fix .

Ejecute con Maven usando Diktat-Maven-Plugin

Puede ver cómo está configurado en nuestros ejemplos:

• Proyecto único
• Proyecto multimódulo

Agregue este complemento a su pom.xml:

            < plugin >
                < groupId >com.saveourtool.diktat</ groupId >
                < artifactId >diktat-maven-plugin</ artifactId >
                < version >${diktat.version}</ version >
                < executions >
                    < execution >
                        < id >diktat</ id >
                        < phase >none</ phase >
                        < goals >
                            < goal >check</ goal >
                            < goal >fix</ goal >
                        </ goals >
                        < configuration >
                            < inputs >
                                < input >${project.basedir}/src/main/kotlin</ input >
                                < input >${project.basedir}/src/test/kotlin</ input >
                            </ inputs >
                            < diktatConfigFile >diktat-analysis.yml</ diktatConfigFile >
                           < excludes >
                              < exclude >${project.basedir}/src/test/kotlin/excluded</ exclude >
                           </ excludes >
                        </ configuration >
                    </ execution >
                </ executions >
            </ plugin >

Para ejecutar DIKTAT en modo comprobado de solo Comando $ mvn diktat:check@diktat . Para ejecutar DIKTAT en modo autocorrecto , use el comando $ mvn diktat:fix@diktat .

Solicitar una executionId de Maven específica en la línea de comando (el diktat final en el ejemplo anterior) puede ser esencial en estos casos:

• En su pom.xml , tiene múltiples ejecuciones con diferentes configuraciones (por ejemplo: conjuntos de reglas múltiples):

  < executions >
  
      < execution >
          < id >diktat-basic</ id >
          < configuration >
              < diktatConfigFile >diktat-analysis.yml</ diktatConfigFile >
          </ configuration >
      </ execution >
  
      < execution >
          < id >diktat-advanced</ id >
          < configuration >
              < diktatConfigFile >diktat-analysis-advanced.yml</ diktatConfigFile >
          </ configuration >
      </ execution >
  
  </ executions >

• Su archivo YAML con reglas Diktat tiene un nombre no defectuoso y/o reside en una ubicación no deformenta:

  < executions >
      < execution >
          < id >diktat</ id >
          < configuration >
              < diktatConfigFile >/non/default/rule-set-file.yml</ diktatConfigFile >
          </ configuration >
      </ execution >
  </ executions >

  • Puede omitir el diktatConfigFile o si apunta al archivo no existido, entonces Diktat se ejecuta con la configuración predeterminada.

Si omite el executionId :

$ mvn diktat:check

-El complemento utilizará la configuración predeterminada y buscará el archivo diktat-analysis.yml en el directorio del proyecto (aún puede personalizar los conjuntos de reglas editando el archivo YAML).

Ejecute con Gradle usando Diktat-Gradle-Plugin

Requiere una versión de Gradle no inferior a 7.0

Puede ver cómo se configura el complemento en nuestros ejemplos:

• Kotlin DSL
• Kotlin DSL para proyecto multimódulo
• Groovy DSL

Agregue este complemento a su `build.gradle.kts`:

plugins {
    id( " com.saveourtool.diktat " ) version " 2.0.0 "
}

Nota Si desea aplicar el complemento a proyectos de múltiples módulos "

 import com.saveourtool.diktat.plugin.gradle.DiktatGradlePlugin

plugins {
    id( " com.saveourtool.diktat " ) version " 2.0.0 " apply false
}

allprojects {
    apply< DiktatGradlePlugin >()
}

Luego puede configurar DIKTAT usando diktat Extension:

diktat {
    inputs {
        include( " src/**/*.kt " )  // path matching this pattern (per PatternFilterable) that will be checked by diktat
        exclude( " src/test/kotlin/excluded/** " )  // path matching this pattern will not be checked by diktat
    }
    debug = true  // turn on debug logging
}

También en diktat Extension puede configurar diferentes reporteros y su salida. Puede especificar json , html , sarif , plain (predeterminado). Si se establece output , debe ser una ruta de archivo. Si no se establece, los resultados se imprimirán en Stdout. Puede especificar múltiples reporteros. Si no se especifica reportero, plain se usará con stdout como salida.

diktat {
    reporters {
        plain()
        json()
        html {
            output = file( " someFile.html " )
        }
        // checkstyle()
        // sarif()
        // gitHubActions()
    }
}

Puede ejecutar cheques DIKTAT usando la tarea ./gradlew diktatCheck y solucionar automáticamente errores con la tarea ./gradlew diktatFix .

Corre con impecable

Spotless es un agregador de uniones.

Graduarse

Diktat se puede ejecutar a través de Spotless-Gradle-Plugin desde la versión 5.10.0

Agregue este complemento a su build.gradle.kts

plugins {
   id( " com.diffplug.spotless " ) version " 5.10.0 "
}

spotless {
   kotlin {
      diktat()
   }
   kotlinGradle {
      diktat()
   }
}

Puede proporcionar una versión de versión y configuración manualmente como confil.

spotless {
   kotlin {
      diktat( " 2.0.0 " ).configFile( " full/path/to/diktat-analysis.yml " )
   }
}

Aturdir

Diktat se puede ejecutar a través de Spotless-Maven-Plugin desde la versión 2.8.0

Agregue este complemento a su pom.xml

< plugin >
   < groupId >com.diffplug.spotless</ groupId >
   < artifactId >spotless-maven-plugin</ artifactId >
   < version >${spotless.version}</ version >
   < configuration >
      < kotlin >
         < diktat />
      </ kotlin >
   </ configuration >
</ plugin >

Puede proporcionar una versión de versión y configuración manualmente como confil.

< diktat >
  < version >2.0.0</ version > <!-- optional -->
  < configFile >full/path/to/diktat-analysis.yml</ configFile > <!-- optional, configuration file path -->
</ diktat >

Integración de Github

Sugerimos que todos usen el formato común "SARIF" como reporter en CI/CD. GitHub tiene una integración con el formato SARIF y le proporciona un informe nativo de los problemas de DIKTAT en solicitudes de extracción.

Integración de Github

1) Agregue la siguiente configuración a la configuración de su proyecto para las acciones de GitHub:

Plugin de graduación:

    githubActions = true

Maven Plugin (pom.xml):

    < githubActions >true</ githubActions >

Maven Plugin (Opciones de CLI):

 mvn -B diktat:check@diktat -Ddiktat.githubActions=true

2. Agregue el siguiente código a su acción GitHub para cargar el informe DIKTAT SARIF (después de que se generó):

      - name : Upload SARIF to Github using the upload-sarif action
        uses : github/codeql-action/upload-sarif@v1
        if : ${{ always() }}
        with :
          sarif_file : ${{ github.workspace }}

NOTA : codeql-action/upload-sarif limita el número de archivos cargados a los 15. Si su proyecto tiene más de 15 subproyectos, se excederá el límite y el paso fallará. Para resolver este tema, se puede fusionar los informes SARIF.

diktat-gradle-plugin proporciona esta capacidad con la tarea mergeDiktatReports . Esta tarea agrega informes de todas las tareas DIKTAT de todos los proyectos de Gradle, que producen informes SARIF, y genera el informe fusionado en el directorio de compilación del Proyecto Root. Entonces este solo archivo se puede usar como una entrada para la acción de GitHub:

 with :
    sarif_file : build/reports/diktat/diktat-merged.sarif 

Personalizaciones a través de diktat-analysis.yml

En Diktat hemos apoyado diktat-analysis.yml que se puede cambiar fácilmente y ayudar a la personalización de su propio conjunto de reglas. Tiene campos simples: name - nombre de la regla, enabled (verdadero/falso) - para habilitar o deshabilitar esa regla (todas las reglas están habilitadas por el valor predeterminado), configuration - un mapa simple de algunas configuraciones únicas adicionales para esta regla en particular. Por ejemplo:

- name : HEADER_MISSING_OR_WRONG_COPYRIGHT
  # all rules are enabled by the default. To disable add 'enabled: false' to the config.
  enabled : true
  configuration :
    isCopyrightMandatory : true
    copyrightText : Copyright (c) Jeff Lebowski, 2012-2020. All rights reserved.

Tenga en cuenta que puede especificar y colocar diktat-analysis.yml que contiene la configuración de DIKTAT en el directorio principal de su proyecto en el mismo nivel donde se almacena build.gradle/pom.xml .
Consulte la configuración predeterminada en diktat-analysis.yml
También vea la lista de todas las reglas respaldadas por Diktat.

Suprimir advertencias/inspecciones

Suprimir advertencias en bloques de código individuales

Además de habilitar/deshabilitar la advertencia a nivel mundial a través del archivo de configuración (`enable = false`), puede suprimir las advertencias agregando anotación`@supress` en bloques de código individuales o `@file: supress ()` anotación en un nivel de archivo.

Por ejemplo:

@Suppress( " FUNCTION_NAME_INCORRECT_CASE " )
class SomeClass {
    fun methODTREE (): String {

    }
}

Deshabilite todas las inspecciones en bloques de código seleccionados

También puede suprimir ** todas las ** advertencias agregando `@supples (" diktat ")` anotación en bloques de código individuales.

Por ejemplo:

@Suppress( " diktat " )
class SomeClass {
    fun methODTREE (): String {

    }
}

Ignoreannotated: Deshabilitar inspecciones en bloques con anotación predefinida

En el archivo `diktat-analysis.yml` para cada inspección, es posible definir una lista de anotaciones que causen deshabilitar la inspección en ese bloque de código en particular:

- name : HEADER_NOT_BEFORE_PACKAGE
  enabled : true
  ignoreAnnotated : [MyAnnotation, Compose, Controller]

Suprimir grupos de inspecciones por capítulos

Es fácil suprimir incluso grupos de inspecciones en Diktat.

Estos grupos están vinculados a capítulos de CodeStyle.

Para deshabilitar los capítulos, deberá agregar la siguiente configuración a la configuración común ( - name: DIKTAT_COMMON ):

    disabledChapters : " 1, 2, 3 "

El mapeo de inspecciones a los capítulos se puede encontrar en grupos de inspecciones.

Corriendo contra la línea de base

Al configurar el análisis de estilo de código en un gran proyecto existente, uno a menudo no tiene la capacidad de corregir todos los hallazgos a la vez. Para permitir la adopción gradual, Diktat y Ktlint admiten el modo de referencia. Al ejecutar Ktlint por primera vez con la línea de base activa, se generará el archivo de línea de base. Es un archivo XML con una lista completa de hallazgos de la herramienta. En invocaciones posteriores, solo se informarán los hallazgos que no están en el archivo de referencia. La línea de base se puede activar con la bandera CLI:

./diktat --baseline=diktat-baseline.xml ** / * .kt

o con las opciones de configuración correspondientes en complementos Maven o Gradle. El informe de línea de base está destinado a agregarse al VCS, pero se puede eliminar y volver a generar más tarde, si es necesario.

Contribución

Vea nuestra política contribuyente y código de conducta

Guía de estilo de codificación de Kotlin (estilo de código DIKTAT), V.1.0.0

Prefacio

• II Propósito de este documento
• I.ii principios generales
• Terminología I.III
• I.IV excepciones

1. Naming

• 1.1 Identificadores
• 1.2 paquetes
• 1.3 clases, enumeraciones, interfaces
• 1.4 Funciones
• 1.5 constantes
• 1.6 Campos no constantes (variables)
  • 1.6.1 Nombre de campo no constante
  • 1.6.2 Nombres de variables booleanas con significado negativo

2. Comentarios

• 2.1 Forma general de KDOC
  • 2.1.1 Uso de KDOC para elementos de código público, protegido o interno
  • 2.1.2 Describir métodos que tienen argumentos, un valor de retorno o pueden lanzar una excepción en el bloque KDOC
  • 2.1.3 Solo un espacio entre la etiqueta KDOC y el contenido. Las etiquetas están organizadas en el orden.
• 2.2 Agregar comentarios en el encabezado del archivo
• 2.3 Comentarios sobre el encabezado de la función
• 2.4 comentarios de código
  • 2.4.1 Agregue una línea en blanco entre el cuerpo del comentario y los bloques de etiquetas kdoc
  • 2.4.2 No comente sobre bloques de código no utilizados
  • 2.4.3 El código entregado al cliente no debe contener comentarios TODO/FixMe

3. Formateo general (tipografía)

• 3.1 Reglas relacionadas con el archivo
  • 3.1.1 Evite los archivos que son demasiado largos
  • 3.1.2 Los bloques de código en el archivo fuente deben separarse mediante una línea en blanco
  • 3.1.3 Orden de declaraciones de importación
  • 3.1.4 Orden de declaración Partes de estructuras de código similares a la clase
  • 3.1.5 Orden de declaración de estructuras de código de nivel superior
• 3.2 aparatos ortopédicos
  • 3.2.1 Uso de aparatos ortopédicos en declaraciones condicionales y bloques de bucle
  • 3.2.2 Los aparatos ortopédicos se colocan al final de la línea en bloques no vacíos y estructuras de bloques
• 3.3 sangría
• 3.4 bloques vacíos
• 3.5 longitud de línea
• 3.6 descansos de línea (líneas nuevas)
  • 3.6.1 Cada línea puede tener un máximo de una declaración
  • 3.6.2 Reglas para ruptura de línea
• 3.7 Uso de líneas en blanco
• 3.8 espacio horizontal
  • 3.8.1 Uso de espacios en blanco para la separación de código
  • 3.8.2 Sin espacios para la alineación horizontal
• 3.9 enumeraciones
• 3.10 Declaración variable
  • 3.10.1 Declarar una variable por línea
  • 3.10.2 Las variables deben declararse cerca de la línea donde se usan por primera vez
• 3.11 'When' Expression
• 3.12 anotaciones
• 3.13 comentarios de bloque
• 3.14 modificadores y valores constantes
  • 3.14.1 Declaración con múltiples modificadores
  • 3.14.2 Valores numéricos largos y separados con un bajo
• 3.15 cadenas
  • 3.15.1 Concatenación de cuerdas
  • 3.15.2 Formato de plantilla de cadena
• 3.16 Declaraciones condicionales
  • 3.16.1 colapsando las declaraciones if redundantes
  • 3.16.2 Condiciones demasiado complejas

4. Variables y tipos

• 4.1 Variables
  • 4.1.1 No use tipos flotantes y dobles cuando se necesitan cálculos precisos
  • 4.1.2 Comparación de valores de tipo flotante numérico
  • 4.1.3 Intenta usar 'Val' en lugar de 'var' para la declaración variable [say_no_to_var]
• 4.2 tipos
  • 4.2.1 Use contratos y elenco inteligente tanto como sea posible
  • 4.2.2 Intente usar alias de tipo para representar los tipos que hacen que el código sea más legible
• 4.3 Declaraciones de seguridad y variables nulas
  • 4.3.1 Evite declarar variables con tipos anulables, especialmente de Kotlin Stdlib
  • 4.3.2 Las variables de tipos genéricos deben tener una declaración de tipo explícito
  • 4.3.3 Seguridad nula

5. Funciones

• 5.1 Diseño de funciones
  • 5.1.1 Evite las funciones que son demasiado largas
  • 5.1.2 Evite la anidación profunda de los bloques de código de función, limitando a cuatro niveles
  • 5.1.3 Evite usar funciones anidadas
  • 5.1.4 Llamadas de función negada
• 5.2 Argumentos de función
  • 5.2.1 El parámetro lambda de la función debe colocarse al final de la lista de argumentos
  • 5.2.2 El número de parámetros de función debe limitarse a cinco
  • 5.2.3 Use valores predeterminados para los argumentos de función en lugar de sobrecargarlos
  • 5.2.4 Código de sincronización dentro del código asíncrono
  • 5.2.5 Los lambdas largos deben tener parámetros explícitos
  • 5.2.6 Evite usar etiqueta innecesaria y personalizada

6. Clases, interfaces y funciones de extensión

• 6.1 clases
  • 6.1.1 denota una clase con un solo constructor
  • 6.1.2 Prefiere clases de datos en lugar de clases sin ninguna lógica funcional
  • 6.1.3 No use el constructor primario si está vacío o inútil
  • 6.1.4 No use bloques init redundantes en su clase
  • 6.1.5 Calificación de supertipo explícito
  • 6.1.6 La clase abstracta debe tener al menos un método abstracto
  • 6.1.7 Al usar el esquema de "Propiedad de respaldo implícito", el nombre de la propiedad real y la espalda debe ser el mismo
  • 6.1.8 Evite usar getters y setters personalizados
  • 6.1.9 Nunca use el nombre de una variable en el getter o setter personalizado (posible_bug)
  • 6.1.10 No se permiten getters y setters triviales en el código
  • 6.1.11 Use 'aplicar' para la inicialización de objetos de agrupación
  • 6.1.12 Prefiere clases en línea cuando una clase tiene una sola propiedad
• 6.2 Funciones de extensión
  • 6.2.1 Use funciones de extensión para hacer que la lógica de las clases sea menos acoplada
  • 6.2.2 No hay funciones de extensión con el mismo nombre y firma si extienden las clases de base y heredera (posible_bug)
  • 6.2.3 No use funciones de extensión para la clase en el mismo archivo
• 6.3 interfaces
• 6.4 objetos
  • 6.4.1 En lugar de usar clases/objetos de utilidad, use extensiones
  • 6.4.2 Los objetos deben usarse para interfaces sin estado
• 6.5 archivos KTS
  • 6.5.1 Los archivos KTS deben envolver la lógica en el alcance de nivel superior

Prefacio

Propósito de este documento

El propósito de este documento es proporcionar una especificación de que los desarrolladores de software puedan hacer referencia para mejorar su capacidad de escribir código consistente, fácil de leer y de alta calidad. Dicha especificación mejorará en última instancia la eficiencia del desarrollo de software y la competitividad del producto. Para que el código se considere de alta calidad, debe implicar las siguientes características:

1. Sencillez
2. Mantenimiento
3. Fiabilidad
4. Probabilidad
5. Eficiencia
6. Portabilidad
7. Reutilización

Principios generales

Al igual que otros lenguajes de programación modernos, Kotlin es un lenguaje de programación avanzado que cumple con los siguientes principios generales:

1. Claridad: una característica necesaria de los programas que son fáciles de mantener y refactorizados.
2. Simplicidad: un código es fácil de entender e implementar.
3. Consistencia: permite que un código se modifique, revise y entiende fácilmente los miembros del equipo. La unificación es particularmente importante cuando el mismo equipo trabaja en el mismo proyecto, utilizando estilos similares, lo que permite modificar, revisar y comprender fácilmente un código fácilmente.

Además, debemos considerar los siguientes factores al programar en Kotlin:

1. Escribir código Kotlin limpio y simple

   Kotlin combina dos de los principales paradigmas de programación: funcionales y orientados a objetos. Ambos paradigmas son prácticas de ingeniería de software confiables y confiables. Como lenguaje de programación joven, Kotlin se basa en los idiomas bien establecidos como Java, C ++, C#y Scala. Esto permite a Kotlin introducir muchas características que ayudan a un desarrollador a escribir un código más limpio y más legible, al tiempo que reducen la cantidad de estructuras de código complejas. Por ejemplo, la seguridad tipo y nula, las funciones de extensión, la sintaxis infix, la inmutabilidad, la diferenciación Val/VAR, las características orientadas a la expresión ", cuando" las declaraciones, mucho más fáciles de trabajar con colecciones, conversión automática de tipo y otro azúcar sintáctico.

2. Siguiendo los modismos de Kotlin

   El autor de Kotlin, Andrey Breslav, mencionó que Kotlin es pragmático y práctico, pero no académico. Sus características pragmáticas permiten que las ideas se transformen en un software de trabajo real fácilmente. Kotlin está más cerca de los idiomas naturales que sus predecesores, e implementa los siguientes principios de diseño: legibilidad, reutilización, interoperabilidad, seguridad y amigable para herramientas (https://blog.jetbrains.com/kotlin/2018/10/kotlinconf-2018-nouncements/).

3. Usando Kotlin de manera eficiente

   Algunas características de Kotlin pueden ayudarlo a escribir código de mayor rendimiento: incluida la biblioteca de Coroutine enriquecida, secuencias, funciones/clases en línea, matrices de tipos básicos, TailRec y llamadas en el contrato.

Terminología

Reglas : convenciones que deben seguirse al programar.

Recomendaciones : convenciones que deben considerarse al programar.

Explicación : explicaciones necesarias de reglas y recomendaciones.

Ejemplo válido : ejemplos recomendados de reglas y recomendaciones.

Ejemplo no válido : no ejemplos recomendados de reglas y recomendaciones.

A menos que se indique lo contrario, esta especificación se aplica a las versiones 1.3 y más tarde de Kotlin.

Excepciones

Aunque pueden existir excepciones, es esencial comprender por qué se necesitan reglas y recomendaciones. Dependiendo de una situación de proyecto o hábitos personales, puede romper algunas de las reglas. Sin embargo, recuerde que una excepción puede conducir a muchos y eventualmente puede destruir la consistencia del código. Como tal, debería haber muy pocas excepciones. Al modificar el código de código abierto o el código de terceros, puede optar por usar el estilo de código de este proyecto de código abierto (en lugar de usar las especificaciones existentes) para mantener la consistencia. El software que se basa directamente en la interfaz del sistema operativo nativo de Android, como el marco de Android, sigue siendo consistente con el estilo de Android.

1. Naming

En la programación, no siempre es fácil nombrar variables, funciones, clases, etc. de manera significativa y de manera significativa ayuda a expresar claramente las ideas y funcionalidades principales de su código y evitar una interpretación errónea, codificación innecesaria y decodificación, números "mágicos" y abreviaturas inapropiadas.

Nota: El formato de codificación del archivo de origen (incluidos los comentarios) debe ser solo UTF-8. El carácter del espacio horizontal ASCII (0x20, es decir, espacio) es el único carácter de espacio blanco permitido. Las pestañas no deben usarse para la sangría.

1.1 Identificadores

Esta sección describe las reglas generales para nombrar identificadores.

1.1.1 Identificadores de nombres de convenciones

Para identificadores, use las siguientes convenciones de nombres:

1. Todos los identificadores deben usar solo letras o dígitos ASCII, y los nombres deben coincidir con expresiones regulares w{2,64} . Explicación: Cada nombre de identificador válido debe coincidir con la expresión regular w{2,64} . {2,64} significa que la longitud del nombre es de 2 a 64 caracteres, y la longitud del nombre de la variable debe ser proporcional a su rango de vida, funcionalidad y responsabilidad. Generalmente se recomiendan longitudes de nombre de menos de 31 caracteres. Sin embargo, esto depende del proyecto. De lo contrario, una declaración de clase con genéricos o herencia de una superclase puede causar ruptura de línea. No se debe usar ningún prefijo o sufijo especial en los nombres. Los siguientes ejemplos son nombres inapropiados: name_, mname, s_name y kname.

2. Elija nombres de archivo que describan el contenido. Use el estuche de camello (Pascalcase) y .kt extensión.

3. Ejemplos típicos de nombres:

Significado	Correcto	Incorrecto
"Solicitud XML HTTP"	Xmlhttprequest	Xmlhttprequest
"nueva identificación del cliente"	nuevo	nuevo
"Stopwatch interno"	inquietud	inquietud
"Admite IPv6 en iOS"	SupportSipv6onios	SupportSipv6onios
"Importador de YouTube"	YouTubeimporter	YouTubeimporter

4. Se prohíbe el uso de (``) y nombres gratuitos para funciones e identificadores. Por ejemplo, no se recomienda el siguiente código:

 val `my dummy name - with - minus` = " value "

La única excepción son los nombres de funciones en Unit tests.

5. Backticks (``) no debe usarse para identificadores, excepto los nombres de los métodos de prueba (marcados con anotación @test):

 @Test fun `my test` () { /* ... */ }

6. La siguiente tabla contiene algunos caracteres que pueden causar confusión. Tenga cuidado al usarlos como identificadores. Para evitar problemas, use otros nombres en su lugar.

Esperado	Nombre confuso	Nombre sugerido
0 (cero)	O, D	obj, DGT
1 (uno)	Yo, L	it, ln, línea
2 (dos)	Z	N1, N2
5 (cinco)	S	XS, STR
6 (seis)	mi	ex, olmo
8 (ocho)	B	BT, NXT
Nueva Hampshire	H, N	nr, cabeza, altura
RN, M	M, RN	MBR, artículo

Excepciones:

• Las variables I, J, K utilizadas en los bucles son parte del estándar de la industria. Se puede usar un símbolo para tales variables.
• La variable e se puede usar para atrapar excepciones en el bloque de captura: catch (e: Exception) {}
• La comunidad Java generalmente no recomienda el uso de prefijos. Sin embargo, al desarrollar el código de Android, puede usar los prefijos S y M para campos no estatales estáticos y no públicos, respectivamente. Tenga en cuenta que el prefijo también puede afectar negativamente el estilo y la auto-generación de getters y setters.

Tipo	Estilo de nombres
Interfaces, clases, anotaciones, tipos enumerados y nombres de tipos de objetos	Caso de camello, comenzando con una letra mayúscula. Las clases de prueba tienen un sufijo de prueba. El nombre de archivo es 'topclassname'.kt.
Campos de clase, variables locales, métodos y parámetros de método	Camel Case comenzando con una carta de caja baja. Los métodos de prueba pueden subrayarse con '_'; La única excepción son las propiedades de respaldo.
Constantes estáticas y valores enumerados	Solo mayúsculas subrayado con '_'
Variable de tipo genérico	Letra mayúscula única, que puede ser seguida por un número, por ejemplo: E, T, U, X, T2
Excepciones	Igual que los nombres de clases, pero con una excepción de sufijo, por ejemplo: AccessException y NullPointerException

1.2 paquetes

Regla 1.2.1 Puntos de nombres de paquetes

Los nombres de los paquetes están en minúsculas y se separan por puntos. El código desarrollado dentro de su empresa debe comenzar con your.company.domain. Los números están permitidos en los nombres de los paquetes. Cada archivo debe tener una directiva package . Los nombres de los paquetes están escritos en minúsculas, y las palabras consecutivas se concatenan juntos (sin subrayadores). Los nombres de los paquetes deben contener los nombres de producto o módulo y el nombre del departamento (o equipo) para evitar conflictos con otros equipos. No se permiten números. Por ejemplo: org.apache.commons.lang3 , xxx.yyy.v2 .

Excepciones:

• En ciertos casos, como proyectos de código abierto o cooperación comercial, los nombres de los paquetes no deben comenzar con your.company.domain.
• Si el nombre del paquete comienza con un número u otro carácter que no se puede usar al comienzo del nombre del paquete Java/Kotlin, entonces se permiten subrayos. Por ejemplo: com.example._123name .
• A veces se permiten subrayos si el nombre del paquete contiene palabras clave Java/Kotlin reservadas, como org.example.hyphenated_name , int_.example .

Ejemplo válido :

 package your.company.domain.mobilecontrol.views

1.3 clases, enumeraciones, typealias, interfaces

Esta sección describe las reglas generales para nombrar clases, enumeraciones e interfaces.

1.3.1 clases, enumeraciones, typealias, nombres de interfaz utilizan casos de camello

Las clases, enumeraciones y nombres de interfaz utilizan la nomenclatura UpperCamelCase . Siga las reglas de nomenclatura que se describen a continuación:

1. Un nombre de clase suele ser un sustantivo (o una frase nominal) denotado usando la nomenclatura del caso de camello, como uppercamelcase. Por ejemplo: Character o ImmutableList . Un nombre de interfaz también puede ser una frase sustantivo o sustantivo (como List ) o una frase adjetiva o adjetiva (como Readable ). Tenga en cuenta que los verbos no se usan para nombrar clases. Sin embargo, se pueden usar sustantivos (como Customer , WikiPage y Account ). Intente evitar usar palabras vagas como Manager y Process .

2. Las clases de prueba comienzan con el nombre de la clase que están probando y terminan con 'prueba'. Por ejemplo, HashTest o HashIntegrationTest .

Ejemplo no válido :

 class marcoPolo {}
class XMLService {}
interface TAPromotion {}
class info {}

Ejemplo válido :

 class MarcoPolo {}
class XmlService {}
interface TaPromotion {}
class Order {}

1.4 Funciones

Esta sección describe las reglas generales para las funciones de nombres.

1.4.1 Los nombres de las funciones deben estar en caso de camello

Los nombres de las funciones deben usar la nomenclatura lowerCamelCase . Siga las reglas de nomenclatura que se describen a continuación:

1. Los nombres de las funciones suelen ser verbos o frases verbales denotadas con la nomenclatura del caso de camello ( lowerCamelCase ). Por ejemplo: sendMessage , stopProcess o calculateValue . Para nombrar funciones, use las siguientes reglas de formato:

a) Obtener, modificar o calcular un cierto valor: Get + no booleano (). Tenga en cuenta que el compilador Kotlin genera automáticamente getters para algunas clases, aplicando la sintaxis especial preferida para los campos 'Get': Kotlin Private Val Field: String get () {}. Campo privado de Kotlin: String get () {}.

 private val field : String
get() {
}

Nota: Se prefiere la sintaxis de acceso a la propiedad de llamadas para llamar directamente a Getter. En este caso, el compilador de Kotlin llama automáticamente al recibo correspondiente.

b) is + nombre de variable booleana ()

c) set + Field/Attribute Name (). Sin embargo, tenga en cuenta que la sintaxis y la generación de código para Kotlin son completamente los mismos que los descritos para los Getters en el punto a.

d) has + sustantivo / adjetivo ()

e) verbo () Nota: Nota: El verbo se usa principalmente para los objetos de acción, como document.print ()

f) verbo + sustantivo ()

g) La función de devolución de llamada permite los nombres que usan el formato de preposición + verbo, como: onCreate() , onDestroy() , toString() .

Ejemplo no válido :

 fun type (): String
fun Finished (): Boolean
fun visible (boolean)
fun DRAW ()
fun KeyListener ( Listener )

Ejemplo válido :

 fun getType (): String
fun isFinished (): Boolean
fun setVisible (boolean)
fun draw ()
fun addKeyListener ( Listener )

2. Se puede incluir un bajo ( _ ) en el nombre de la función de prueba JUnit y debe usarse como separador. Cada parte lógica se denota en lowerCamelCase , por ejemplo, un patrón típico de usar un bajo: pop_emptyStack .

1.5 constantes

Esta sección describe las reglas generales para las restricciones de nombres.

1.5.1 Uso de los caracteres de mayúsculas y subrayadores en un nombre de restricción

Los nombres constantes deben estar en el primer caso, palabras separadas por bajo. Las convenciones generales de nombres constantes se enumeran a continuación:

1. Las constantes son atributos creados con la palabra clave const o variables locales de nivel superior/ val de un objeto que contiene datos inmutables. En la mayoría de los casos, las constantes se pueden identificar como una propiedad const val del nivel superior de object / companion object / archivo. Estas variables contienen valores constantes fijos que generalmente nunca deben ser cambiados por los programadores. Esto incluye tipos básicos, cadenas, tipos inmutables y colecciones inmutables de tipos inmutables. El valor no es constante para el objeto, qué estado se puede cambiar.
2. Los nombres constantes deben contener solo letras mayúsculas separadas por un subrayado. Deben tener un modificador Val o const Val para que sean finales explícitamente. En la mayoría de los casos, si necesita especificar un valor constante, debe crearlo con el modificador "const val". Tenga en cuenta que no todas las variables val son constantes.
3. Los objetos con contenido inmutable, como Logger y Lock , pueden estar en mayúsculas como constantes o tener un caso de camello como variables regulares.
4. Use constantes significativas en lugar de magic numbers . SQL o cadenas de registro no deben tratarse como números mágicos, ni deben definirse como constantes de cadena. Las constantes mágicas, como NUM_FIVE = 5 o NUM_5 = 5 no deben tratarse como constantes. Esto se debe a que los errores se realizarán fácilmente si se cambian a NUM_5 = 50 o 55. Estas constantes generalmente representan valores lógicos comerciales, como medidas, capacidad, alcance, ubicación, tasa impositiva, descuentos promocionales y múltiplos de base de potencia en algoritmos. Puede evitar usar números mágicos con el siguiente método:

• Uso de funciones de biblioteca y API. Por ejemplo, en lugar de verificar ese size == 0 , use la función isEmpty() . Para trabajar con time , use los empotrados de java.time API .
• Las enumeraciones se pueden usar para nombrar patrones. Consulte el escenario de uso recomendado para la enumeración en 3.9.

Ejemplo no válido :

 var int MAXUSERNUM = 200 ;
val String sL = " Launcher " ;

Ejemplo válido :

 const val int MAX_USER_NUM = 200 ;
const val String APPLICATION_NAME = " Launcher " ;

1.6 Campos no constantes (variables)

Esta sección describe las reglas generales para nombrar variables.

1.6.1 Nombre de campo no constante

Los nombres de campo no constantes deben usar una caja de camello y comenzar con una letra minúscula. Una variable local no puede tratarse como constante incluso si es final e inmutable. Por lo tanto, no debe usar las reglas anteriores. Los nombres de las variables de tipo de colección (conjuntos, listas, etc.) deben contener sustantivos plurales. Por ejemplo: var namesList: List<String>

Los nombres de las variables no constantes deben usar lowerCamelCase . El nombre del campo inmutable final utilizado para almacenar el objeto Singleton puede usar la misma notación de casos de camello.

Ejemplo no válido :

customername : String
user : List < String > = listof()

Ejemplo válido :

 var customerName : String
val users : List < String > = listOf ();
val mutableCollection : MutableSet < String > = HashSet ()

1.6.2 Nombres de variables booleanas con significado negativo

Evite usar nombres de variables booleanas con un significado negativo. Al usar un operador lógico y un nombre con un significado negativo, el código puede ser difícil de entender, que se conoce como "doble negativo". Por ejemplo, no es fácil entender el significado de! Isnoterror. La especificación de Javabeans genera automáticamente los getters isxxx () para atributos de clases booleanas. Sin embargo, no todos los métodos que devuelven el tipo booleano tienen esta notación. Para las variables o métodos locales booleanos, se recomienda encarecidamente que agregue prefijos no intencionados, incluidos los IS (comúnmente utilizado por Javabeans), tienen, pueden, deberían y lo hay. Los entornos de desarrollo integrados modernos (IDE) como IntelliJ ya son capaces de hacerlo por usted cuando generas Getters en Java. Para Kotlin, este proceso es aún más sencillo ya que todo está en el nivel de código de bytes debajo del capó.

Ejemplo no válido :

 val isNoError : Boolean
val isNotFound : Boolean
fun empty ()
fun next ();

Ejemplo válido :

 val isError : Boolean
val isFound : Boolean
val hasLicense : Boolean
val canEvaluate : Boolean
val shouldAbort : Boolean
fun isEmpty ()
fun hasNext ()

2. Comentarios

La mejor práctica es comenzar su código con un resumen, que puede ser una oración. Intente equilibrar entre no escribir comentarios y declaraciones de comentarios obvias para cada línea de código. Los comentarios deben expresarse con precisión y claramente, sin repetir el nombre de la clase, la interfaz o el método. Los comentarios no son una solución al código incorrecto. En su lugar, debe solucionar el código tan pronto como note un problema o planee solucionarlo (ingresando un comentario de TODO, incluido un número JIRA). Los comentarios deben reflejar con precisión las ideas de diseño y la lógica del código y describir más su lógica comercial. Como resultado, otros programadores podrán ahorrar tiempo al intentar comprender el código. Imagine que está escribiendo los comentarios para ayudarse a comprender las ideas originales detrás del código en el futuro.

2.1 Forma general de KDOC

KDOC es una combinación de la sintaxis de las etiquetas de bloque de Javadoc (extendidas para admitir construcciones específicas de Kotlin) y el marcado en línea de Markdown. El formato básico de KDOC se muestra en el siguiente ejemplo:

 /* *
 * There are multiple lines of KDoc text,
 * Other ...
 */
fun method ( arg : String ) {
    // ...
}

También se muestra en el siguiente formulario de una sola línea:

 /* * Short form of KDoc. */

Use un formulario de una sola línea cuando almacene todo el bloque KDOC en una línea (y no hay KDOC Mark @xxx). Para obtener instrucciones detalladas sobre cómo usar KDOC, consulte el documento oficial.

2.1.1 Uso de KDOC para elementos de código público, protegido o interno

Como mínimo, KDOC debe usarse para cada clase, interfaz, enumeración, método y campo de miembros (propiedad) públicas, protegidas o internas. Otros bloques de código también pueden tener KDOC si es necesario. En lugar de usar comentarios o KDOCs antes de las propiedades en el constructor primario de una clase, use @property Tag en un KDOC de una clase. Todas las propiedades del constructor primario también deben documentarse en un KDOC con una etiqueta @property .

Ejemplo incorrecto:

 /* *
 * Class description
 */
class Example (
 /* *
  * property description
  */
  val foo : Foo ,
  // another property description
  val bar : Bar
)

Ejemplo correcto:

 /* *
 * Class description
 * @property foo property description
 * @property bar another property description
 */
class Example (
  val foo : Foo ,
  val bar : Bar
)

• No use los comentarios de KDOC dentro de los bloques de código como comentarios de bloque

Ejemplo incorrecto:

 class Example {
  fun doGood () {
    /* *
     * wrong place for kdoc
     */
    1 + 2
  }
}

Ejemplo correcto:

 class Example {
  fun doGood () {
    /*
     * right place for block comment
    */
    1 + 2
  }
}

Excepciones:

• Para los setters/getters of propiedades, los comentarios obvios (como this getter returns field ) son opcionales. Tenga en cuenta que Kotlin genera métodos simples get/set debajo del capó.

• Es opcional agregar comentarios para métodos simples de una línea, como se muestra en el ejemplo a continuación:

 val isEmpty : Boolean
    get() = this .size == 0

o

 fun isEmptyList ( list : List < String >) = list.size == 0

Nota: Puede omitir KDOCS para obtener la anulación de un método si es casi lo mismo que el método de superclase.

2.1.2 Describir métodos que tienen argumentos, un valor de retorno o pueden lanzar una excepción en el bloque KDOC

Cuando el método tiene detalles como argumentos, valor de retorno o puede arrojar excepciones, debe describirse en el bloque KDOC (con @param, @return, @throws, etc.).

Ejemplos válidos:

 /* *
* This is the short overview comment for the example interface.
*     / * Add a blank line between the comment text and each KDoc tag underneath * /
* @since 1.6
*/
protected abstract class Sample {
   /* *
    * This is a long comment with whitespace that should be split in
    * comments on multiple lines if the line comment formatting is enabled.
    *     / * Add a blank line between the comment text and each KDoc tag underneath * /
    * @param fox A quick brown fox jumps over the lazy dog
    * @return battle between fox and dog
    */
   protected abstract fun foo ( Fox fox)
    /* *
     * These possibilities include: Formatting of header comments
     *     / * Add a blank line between the comment text and each KDoc tag underneath * /
     * @return battle between fox and dog
     * @throws ProblemException if lazy dog wins
     */
   protected fun bar () throws ProblemException {
       // Some comments / * No need to add a blank line here * /
       var aVar = .. .

       // Some comments  / * Add a blank line before the comment * /
       fun doSome ()
   }
}

2.1.3 Solo un espacio entre la etiqueta KDOC y el contenido. Las etiquetas están organizadas en el orden.

Solo debe haber un espacio entre la etiqueta KDOC y el contenido. Las etiquetas se organizan en el siguiente orden: @param, @return y @throws.

Por lo tanto, KDOC debe contener lo siguiente:

• Descripción funcional y técnica, explicando los principios, intenciones, contratos, API, etc.
• La descripción de la función y @tags ( implSpec , apiNote e implNote ) requieren una línea vacía después de ellos.
• @implSpec : una especificación relacionada con la implementación de API, y debe permitir que el implementador decida si lo anula.
• @apiNote : explique las precauciones de la API, que incluyen si permitir nulo y si el método es seguro de subprocesos, así como la complejidad del algoritmo, la entrada y el rango de salida, las excepciones, etc.
• @implNote : una nota relacionada con la implementación de API, que los implementadores deben tener en cuenta.
• Una línea vacía, seguida de @param regular, @return , @throws y otros comentarios.
• Las "etiquetas de bloques" estándar convencionales se organizan en el siguiente orden: @param , @return , @throws . KDOC no debe contener:
• Descripciones vacías en bloques de etiquetas. Es mejor no escribir KDOC que el espacio de la línea de código de residuos.
• No debe haber líneas vacías entre la declaración del método/ clase y el final de KDOC ( */ símbolos).
• @author Etiqueta. No importa quién creó originalmente una clase cuando puede usar git blame o VCS de su elección para mirar a través del historial de cambios. Notas importantes:
• KDOC no admite la etiqueta @deprecated . En su lugar, use la anotación @Deprecated .
• La etiqueta @since debe usarse solo para versiones. No use fechas en la etiqueta @since , es confuso y menos preciso.

Si un bloque de etiquetas no se puede describir en una línea, envíe el contenido de la nueva línea por cuatro espacios desde la posición @ para lograr la alineación ( @ cuenta como uno + tres espacios).

Excepción:

When the descriptive text in a tag block is too long to wrap, you can indent the alignment with the descriptive text in the last line. The descriptive text of multiple tags does not need to be aligned. See 3.8 Horizontal space.

In Kotlin, compared to Java, you can put several classes inside one file, so each class should have a Kdoc formatted comment (as stated in rule 2.1). This comment should contain @since tag. The right style is to write the application version when its functionality is released. It should be entered after the @since tag.

Ejemplos:

 /* *
 * Description of functionality
 *
 * @since 1.6
 */

Other KDoc tags (such as @param type parameters and @see.) can be added as follows:

 /* *
 * Description of functionality
 *
 * @apiNote: Important information about API
 *
 * @since 1.6
 */

2.2 Adding comments on the file header

This section describes the general rules of adding comments on the file header.

2.2.1 Formatting of comments in the file header

Comments on the file header should be placed before the package name and imports. If you need to add more content to the comment, subsequently add it in the same format.

Comments on the file header must include copyright information, without the creation date and author's name (use VCS for history management). Also, describe the content inside files that contain multiple or no classes.

The following examples for Huawei describe the format of the copyright license :
Chinese version:版权所有 (c) 华为技术有限公司 2012-2020
English version: Copyright (c) Huawei Technologies Co., Ltd. 2012-2020. All rights reserved. 2012 and 2020 are the years the file was first created and the current year, respectively.

Do not place release notes in header, use VCS to keep track of changes in file. Notable changes can be marked in individual KDocs using @since tag with version.

Invalid example:

 /* *
 * Release notes:
 * 2019-10-11: added class Foo
 */

class Foo

Valid example:

 /* *
 * @since 2.4.0
 */
class Foo

• The copyright statement can use your company's subsidiaries, as shown in the below examples:
  Chinese version:版权所有 (c) 海思半导体 2012-2020
  English version: Copyright (c) Hisilicon Technologies Co., Ltd. 2012-2020. All rights reserved.

• The copyright information should not be written in KDoc style or use single-line comments. It must start from the beginning of the file. The following example is a copyright statement for Huawei, without other functional comments:

 /*
 * Copyright (c) Huawei Technologies Co., Ltd. 2012-2020. All rights reserved.
 */

The following factors should be considered when writing the file header or comments for top-level classes:

• File header comments must start from the top of the file. If it is a top-level file comment, there should be a blank line after the last Kdoc */ symbol. If it is a comment for a top-level class, the class declaration should start immediately without using a newline.
• Maintain a unified format. The specific format can be formulated by the project (for example, if you use an existing opensource project), and you need to follow it.
• A top-level file-Kdoc must include a copyright and functional description, especially if there is more than one top-level class.
• Do not include empty comment blocks. If there is no content after the option @apiNote , the entire tag block should be deleted.
• The industry practice is not to include historical information in the comments. The corresponding history can be found in VCS (git, svn, etc.). Therefore, it is not recommended to include historical data in the comments of the Kotlin source code.

2.3 Comments on the function header

Comments on the function header are placed above function declarations or definitions. A newline should not exist between a function declaration and its Kdoc. Use the preceding <<c2.1,KDoc>> style rules.

As stated in Chapter 1, the function name should reflect its functionality as much as possible. Therefore, in the Kdoc, try to describe the functionality that is not mentioned in the function name. Avoid unnecessary comments on dummy coding.

The function header comment's content is optional, but not limited to function description, return value, performance constraints, usage, memory conventions, algorithm implementation, reentrant requirements, etc.

2.4 Code comments

This section describes the general rules of adding code comments.

2.4.1 Add a blank line between the body of the comment and Kdoc tag-blocks.

It is a good practice to add a blank line between the body of the comment and Kdoc tag-blocks. Also, consider the following rules:

• There must be one space between the comment character and the content of the comment.
• There must be a newline between a Kdoc and the presiding code.
• An empty line should not exist between a Kdoc and the code it is describing. You do not need to add a blank line before the first comment in a particular namespace (code block) (for example, between the function declaration and first comment in a function body).

Valid Examples:

 /* *
 * This is the short overview comment for the example interface.
 *
 * @since 1.6
 */
 public interface Example {
    // Some comments  /* Since it is the first member definition in this code block, there is no need to add a blank line here */
    val aField : String = .. .
                     /* Add a blank line above the comment */
    // Some comments
    val bField : String = .. .
                      /* Add a blank line above the comment */
    /* *
     * This is a long comment with whitespace that should be split in
     * multiple line comments in case the line comment formatting is enabled.
     *                /* blank line between description and Kdoc tag */
     * @param fox A quick brown fox jumps over the lazy dog
     * @return the rounds of battle of fox and dog
     */
    fun foo ( Fox fox)
                      /* Add a blank line above the comment */
     /* *
      * These possibilities include: Formatting of header comments
      *
      * @return the rounds of battle of fox and dog
      * @throws ProblemException if lazy dog wins
      */
    fun bar () throws ProblemException {
        // Some comments  /* Since it is the first member definition in this range, there is no need to add a blank line here */
        var aVar = .. .

        // Some comments  /* Add a blank line above the comment */
        fun doSome ()
    }
 }

• Leave one single space between the comment on the right side of the code and the code. If you use conditional comments in the if-else-if scenario, put the comments inside the else-if branch or in the conditional block, but not before the else-if . This makes the code more understandable. When the if-block is used with curly braces, the comment should be placed on the next line after opening the curly braces. Compared to Java, the if statement in Kotlin statements returns a value. For this reason, a comment block can describe a whole if-statement .

Valid examples:

 val foo = 100  // right-side comment
val bar = 200  /* right-side comment */

// general comment for the value and whole if-else condition
val someVal = if (nr % 15 == 0 ) {
    // when nr is a multiple of both 3 and 5
    println ( " fizzbuzz " )
} else if (nr % 3 == 0 ) {
    // when nr is a multiple of 3, but not 5
    // We print "fizz", only.
    println ( " fizz " )
} else if (nr % 5 == 0 ) {
    // when nr is a multiple of 5, but not 3
    // we print "buzz" only.
    println ( " buzz " )
} else {
    // otherwise, we print the number.
    println (x)
}

• Start all comments (including KDoc) with a space after the first symbol ( // , /* , /** and * )

Valid example:

 val x = 0  // this is a comment 

2.4.2 Do not comment on unused code blocks

Do not comment on unused code blocks, including imports. Delete these code blocks immediately. A code is not used to store history. Git, svn, or other VCS tools should be used for this purpose. Unused imports increase the coupling of the code and are not conducive to maintenance. The commented out code cannot be appropriately maintained. In an attempt to reuse the code, there is a high probability that you will introduce defects that are easily missed. The correct approach is to delete the unnecessary code directly and immediately when it is not used anymore. If you need the code again, consider porting or rewriting it as changes could have occurred since you first commented on the code.

2.4.3 Code delivered to the client should not contain TODO/FIXME comments

The code officially delivered to the client typically should not contain TODO/FIXME comments. TODO comments are typically used to describe modification points that need to be improved and added. For example, refactoring FIXME comments are typically used to describe known defects and bugs that will be subsequently fixed and are not critical for an application. They should all have a unified style to facilitate unified text search processing.

Ejemplo:

 // TODO(<author-name>): Jira-XXX - support new json format
// FIXME: Jira-XXX - fix NPE in this code block

At a version development stage, these annotations can be used to highlight the issues in the code, but all of them should be fixed before a new product version is released.

3. General formatting (typesetting)

3.1 File-related rules

This section describes the rules related to using files in your code.

3.1.1 Avoid files that are too long

If the file is too long and complicated, it should be split into smaller files, functions, or modules. Files should not exceed 2000 lines (non-empty and non-commented lines). It is recommended to horizontally or vertically split the file according to responsibilities or hierarchy of its parts. The only exception to this rule is code generation - the auto-generated files that are not manually modified can be longer.

3.1.2 Code blocks in the source file should be separated by one blank line

A source file contains code blocks in the following order: copyright, package name, imports, and top-level classes. They should be separated by one blank line.

a) Code blocks should be in the following order:

1. Kdoc for licensed or copyrighted files
2. @file annotation
3. Nombre del paquete
4. Import statements
5. Top-class header and top-function header comments
6. Top-level classes or functions

b) Each of the preceding code blocks should be separated by a blank line.

c) Import statements are alphabetically arranged, without using line breaks and wildcards ( wildcard imports - * ).

d) Recommendation : One .kt source file should contain only one class declaration, and its name should match the filename

e) Avoid empty files that do not contain the code or contain only imports/comments/package name

f) Unused imports should be removed

3.1.3 Import statements order

From top to bottom, the order is the following:

1. Androide
2. Imports of packages used internally in your organization
3. Imports from other non-core dependencies
4. Java core packages
5. kotlin stdlib

Each category should be alphabetically arranged. Each group should be separated by a blank line. This style is compatible with Android import order.

Valid example :

 import android.* // android
import androidx.* // android
import com.android.* // android

import com.your.company.* // your company's libs
import your.company.* // your company's libs

import com.fasterxml.jackson.databind.ObjectMapper // other third-party dependencies
import org.junit.jupiter.api.Assertions

import java.io.IOException // java core packages
import java.net.URL

import kotlin.system.exitProcess  // kotlin standard library
import kotlinx.coroutines.*  // official kotlin extension library 

3.1.4 Order of declaration parts of class-like code structures

The declaration parts of class-like code structures (class, interface, etc.) should be in the following order: compile-time constants (for objects), class properties, late-init class properties, init-blocks, constructors, public methods, internal methods, protected methods, private methods, and companion object. Blank lines should separate their declaration. Notas:

1. There should be no blank lines between properties with the following exceptions : when there is a comment before a property on a separate line or annotations on a separate line.
2. Properties with comments/Kdoc should be separated by a newline before the comment/Kdoc.
3. Enum entries and constant properties ( const val ) in companion objects should be alphabetically arranged.

The declaration part of a class or interface should be in the following order:

• Compile-time constants (for objects)
• Propiedades
• Late-init class properties
• Init-blocks
• Constructores
• Methods or nested classes. Put nested classes next to the code they are used by. If the classes are meant to be used externally, and are not referenced inside the class, put them after the companion object.
• Companion object

Exception: All variants of a private val logger should be placed at the beginning of the class ( private val log , LOG , logger , etc.).

3.1.5 Order of declaration of top-level code structures

Kotlin allows several top-level declaration types: classes, objects, interfaces, properties and functions. When declaring more than one class or zero classes (eg only functions), as per rule 2.2.1, you should document the whole file in the header KDoc. When declaring top-level structures, keep the following order:

1. Top-level constants and properties (following same order as properties inside a class: const val , val , lateinit var , var )
2. typealiases (grouped by their visibility modifiers)
3. Interfaces, classes and objects (grouped by their visibility modifiers)
4. Extension functions
5. Other functions

Note : Extension functions shouldn't have receivers declared in the same file according to rule 6.2.3

Valid example:

 package com.saveourtool.diktat.example

const val CONSTANT = 42

val topLevelProperty = " String constant "

internal typealias ExamplesHandler = ( IExample ) -> Unit

interface IExample

class Example : IExample

private class Internal

fun Other. asExample (): Example { /* ... */ }

private fun Other. asInternal (): Internal { /* ... */ }

fun doStuff () { /* ... */ }

Note : kotlin scripts (.kts) allow arbitrary code to be placed on the top level. When writing kotlin scripts, you should first declare all properties, classes and functions. Only then you should execute functions on top level. It is still recommended wrapping logic inside functions and avoid using top-level statements for function calls or wrapping blocks of code in top-level scope functions like run .

Ejemplo:

 /* class declarations */
/* function declarations */
run {
    // call functions here
}

3.2 Braces

This section describes the general rules of using braces in your code.

3.2.1 Using braces in conditional statements and loop blocks

Braces should always be used in if , else , for , do , and while statements, even if the program body is empty or contains only one statement. In special Kotlin when statements, you do not need to use braces for single-line statements.

Valid example:

 when (node.elementType) {
    FILE -> {
        checkTopLevelDoc(node)
        checkSomething()
     }
    CLASS -> checkClassElements(node)
}

Exception: The only exception is ternary operator in Kotlin (a single line if () <> else <> )

Invalid example:

 val value = if (string.isEmpty())  // WRONG!
                0
            else
                1

Valid example :

 val value = if (string.isEmpty()) 0 else 1  // Okay 

 if (condition) {
    println ( " test " )
} else {
    println ( 0 )
}

3.2.2 Opening braces are placed at the end of the line in non-empty blocks and block structures

For non-empty blocks and block structures, the opening brace is placed at the end of the line. Follow the K&R style (1TBS or OTBS) for non-empty code blocks with braces:

• The opening brace and first line of the code block are on the same line.
• The closing brace is on its own new line.
• The closing brace can be followed by a newline character. The only exceptions are else , finally , and while (from do-while statement), or catch keywords. These keywords should not be split from the closing brace by a newline character.

Exception cases :

1. For lambdas, there is no need to put a newline character after the first (function-related) opening brace. A newline character should appear only after an arrow ( -> ) (see point 5 of Rule 3.6.2).

arg.map { value ->
    foo(value)
}

2. for else / catch / finally / while (from do-while statement) keywords closing brace should stay on the same line:

 do {
   if ( true ) {
       x ++
   } else {
       x --
   }
} while (x > 0 )

Valid example:

       return arg.map { value ->
           while (condition()) {
               method()
           }
           value
       }

       return MyClass () {
           @Override
             fun method () {
               if (condition()) {
                   try {
                       something()
                   } catch (e : ProblemException ) {
                       recover()
                   }
               } else if (otherCondition()) {
                   somethingElse()
               } else {
                   lastThing()
               }
           }
       }

3.3 Indentation

Only spaces are permitted for indentation, and each indentation should equal four spaces (tabs are not permitted). If you prefer using tabs, simply configure them to change to spaces in your IDE automatically. These code blocks should be indented if they are placed on the new line, and the following conditions are met:

• The code block is placed immediately after an opening brace.
• The code block is placed after each operator, including the assignment operator ( + / - / && / = /etc.)
• The code block is a call chain of methods:

someObject
    .map()
    .filter()

• The code block is placed immediately after the opening parenthesis.
• The code block is placed immediately after an arrow in lambda:

arg.map { value ->
   foo(value)
}

Exceptions :

1. Argument lists:
   a) Eight spaces are used to indent argument lists (both in declarations and at call sites).
   b) Arguments in argument lists can be aligned if they are on different lines.

2. Eight spaces are used if there is a newline after any binary operator.

3. Eight spaces are used for functional-like styles when the newline is placed before the dot.

4. Supertype lists:
   a) Four spaces are used if the colon before the supertype list is on a new line.
   b) Four spaces are used before each supertype, and eight spaces are used if the colon is on a new line.

Note: there should be an indentation after all statements such as if , for , etc. However, according to this code style, such statements require braces.

 if (condition)
    foo()

Exceptions :

• When breaking the parameter list of a method/class constructor, it can be aligned with 8 spaces . A parameter that was moved to a new line can be on the same level as the previous argument:

 fun visit (
        node : ASTNode ,
        autoCorrect : Boolean ,
        params : KtLint . ExperimentalParams ,
        emit : (offset: Int , errorMessage: String , canBeAutoCorrected: Boolean ) -> Unit
) {
}

• Such operators as + / - / * can be indented with 8 spaces :

 val abcdef = " my splitted " +
                " string "

• Opening and closing quotes in multiline string should have same indentation

lintMethod(
            """
                    |val q = 1
                    |
            """ .trimMargin()
    )

• A list of supertypes should be indented with 4 spaces if they are on different lines or with 8 spaces if the leading colon is also on a separate line

 class A :
    B ()

class A
    :
        B ()

3.4 Empty blocks

Avoid empty blocks, and ensure braces start on a new line. An empty code block can be closed immediately on the same line and the next line. However, a newline is recommended between opening and closing braces {} (see the examples below.)

Generally, empty code blocks are prohibited; using them is considered a bad practice (especially for catch block). They are appropriate for overridden functions, when the base class's functionality is not needed in the class-inheritor, for lambdas used as a function and for empty function in implementation of functional interface.

 override fun foo () {
}

Valid examples (note once again that generally empty blocks are prohibited):

 fun doNothing () {}

fun doNothingElse () {
}

fun foo ( bar : () -> Unit = {})

Invalid examples:

 try {
  doSomething()
} catch (e : Some ) {}

Use the following valid code instead:

 try {
   doSomething()
} catch (e : Some ) {
}

3.5 Line length

Line length should be less than 120 symbols. Otherwise, it should be split.

If complex property initializing is too long, It should be split into priorities:

1. Logic Binary Expression (&& ||)
2. Comparison Binary Expression (> < == >= <= !=)
3. Other types (Arithmetical and Bit operation) (+ - * / % >> << *= += -= /= %= ++ -- ! in !in etc)

Invalid example:

 val complexProperty = 1 + 2 + 3 + 4

Valid example:

 val complexProperty = 1 + 2 +
    3 + 4

Invalid example:

 val complexProperty = ( 1 + 2 + 3 > 0 ) && ( 23 * 4 > 10 * 6 )

Valid example:

 val complexProperty = ( 1 + 2 + 3 > 0 ) &&
    ( 23 * 4 > 10 * 6 )

If long line should be split in Elvis Operator (?:), it`s done like this

Invalid example:

 val value = first ? : second

Valid example:

 val value = first
    ? : second

If long line in Dot Qualified Expression or Safe Access Expression , it`s done like this:

Invalid example:

 val value = This . Is . Very . Long . Dot . Qualified . Expression

Valid example:

 val value = This . Is . Very . Long
    . Dot . Qualified . Expression

Invalid example:

 val value = This . Is ?. Very ?. Long? . Safe ?. Access ?. Expression

Valid example:

 val value = This . Is ?. Very ?. Long
    ?. Safe ?. Access ?. Expression

if value arguments list is too long, it also should be split:

Invalid example:

 val result1 = ManyParamInFunction (firstArgument, secondArgument, thirdArgument, fourthArgument, fifthArguments)

Valid example:

 val result1 = ManyParamInFunction (firstArgument,
 secondArgument, thirdArgument, fourthArgument,
 fifthArguments)

If annotation is too long, it also should be split:

Invalid example:

@Query(value = " select * from table where age = 10 " , nativeQuery = true )
fun foo () {}

Valid example:

@Query(
    value = " select * from table where age = 10 " ,
    nativeQuery = true )
fun foo () {}

Long one line function should be split:

Invalid example:

 fun foo () = goo().write( " TooLong " )

Valid example:

 fun foo () =
    goo().write( " TooLong " )

Long binary expression should be split into priorities:

1. Logic Binary Expression ( && || )
2. Comparison Binary Expression ( > < == >= <= != )
3. Other types (Arithmetical and Bit operation) ( + - * / % >> << /*= += -= /= %= ++ -- ! in !in etc)

Invalid example:

 if (( x >  100 ) || y < 100 && ! isFoo()) {}

Valid example:

 if (( x >  100 ) ||
    y < 100 && ! isFoo()) {}

String template also can be split in white space in string text

Invalid example:

 val nameString = " This is very long string template "

Valid example:

 val nameString = " This is very long " +
        " string template "

Long Lambda argument should be split:

Invalid example:

 val variable = a?.filter { it.elementType == true } ? : null

Valid example:

 val variable = a?.filter {
    it.elementType == true
} ? : null

Long one line When Entry should be split:

Invalid example:

 when (elem) {
    true -> long.argument.whenEntry
}

Valid example:

 when (elem) {
    true -> {
        long.argument.whenEntry
    }
}

If the examples above do not fit, but the line needs to be split and this in property , this is fixed like thisЖ

Invalid example:

 val element = veryLongNameFunction(firstParam)

Valid example:

 val element =
    varyLongNameFunction(firstParam)

Eol comment also can be split, but it depends on comment location. If this comment is on the same line with code it should be on line before:

Invalid example:

 fun foo () {
    val name = " Nick " // this comment is too long
}

Valid example:

 fun foo () {
    // this comment is too long
    val name = " Nick "
}

But if this comment is on new line - it should be split to several lines:

Invalid example:

 // This comment is too long. It should be on two lines.
fun foo () {}

Valid example:

 // This comment is too long.
// It should be on two lines.
fun foo () {}

The international code style prohibits non-Latin ( non-ASCII ) symbols. (See Identifiers) However, if you still intend on using them, follow the following convention:

• One wide character occupies the width of two narrow characters. The "wide" and "narrow" parts of a character are defined by its east Asian width Unicode attribute. Typically, narrow characters are also called "half-width" characters. All characters in the ASCII character set include letters (such as a, A ), numbers (such as 0, 3 ), and punctuation spaces (such as , , { ), all of which are narrow characters. Wide characters are also called "full-width" characters. Chinese characters (such as中, 文), Chinese punctuation ( ， , ； ), full-width letters and numbers (such as Ａ、３ ) are "full-width" characters. Each one of these characters represents two narrow characters.

• Any line that exceeds this limit ( 120 narrow symbols ) should be wrapped, as described in the Newline section.

Exceptions:

1. The long URL or long JSON method reference in KDoc.
2. The package and import statements.
3. The command line in the comment, enabling it to be cut and pasted into the shell for use.

3.6 Line breaks (newlines)

This section contains the rules and recommendations on using line breaks.

3.6.1 Each line can have a maximum of one statement

Each line can have a maximum of one code statement. This recommendation prohibits the use of code with ; because it decreases code visibility.

Invalid example:

 val a = " " ; val b = " "

Valid example:

 val a = " "
val b = " " 

3.6.2 Rules for line-breaking

1. Unlike Java, Kotlin allows you not to put a semicolon ( ; ) after each statement separated by a newline character. There should be no redundant semicolon at the end of the lines.

When a newline character is needed to split the line, it should be placed after such operators as && / || / + /etc. and all infix functions (for example, xor ). However, the newline character should be placed before operators such as . , ?. , ?: , y :: .

Note that all comparison operators, such as == , > , < , should not be split.

Invalid example :

     if (node !=
             null && test != null ) {}

Valid example :

         if (node != null &&
                 test != null ) {
         }

Note: You need to follow the functional style, meaning each function call in a chain with . should start at a new line if the chain of functions contains more than one call:

  val value = otherValue !!
          .map { x -> x }
          .filter {
              val a = true
              true
          }
          .size

Note: The parser prohibits the separation of the !! operator from the value it is checking.

Exception : If a functional chain is used inside the branches of a ternary operator, it does not need to be split with newlines.

Valid example :

 if (condition) list.map { foo(it) }.filter { bar(it) } else list.drop( 1 )

Note: If dot qualified expression is inside condition or passed as an argument - it should be replaced with new variable.

Invalid example :

 if (node.treeParent.treeParent?.treeParent.findChildByType( IDENTIFIER ) != null ) {}

Valid example :

        val grandIdentifier = node
            .treeParent
            .treeParent
            ?.treeParent
            .findChildByType( IDENTIFIER )
        if (grandIdentifier != null ) {}

Second valid example :

        val grandIdentifier = node.treeParent
            .treeParent
            ?.treeParent
            .findChildByType( IDENTIFIER )
        if (grandIdentifier != null ) {}

2. Newlines should be placed after the assignment operator ( = ).
3. In function or class declarations, the name of a function or constructor should not be split by a newline from the opening brace ( . A brace should be placed immediately after the name without any spaces in declarations or at call sites.
4. Newlines should be placed right after the comma ( , ).
5. If a lambda statement contains more than one line in its body, a newline should be placed after an arrow if the lambda statement has explicit parameters. If it uses an implicit parameter ( it ), the newline character should be placed after the opening brace ( { ). The following examples illustrate this rule:

Invalid example:

    value.map { name -> foo()
        bar()
    }

Valid example:

value.map { name ->
    foo()
    bar()
}

val someValue = { node : String -> node }

6. When the function contains only a single expression, it can be written as expression function. The below example shows the style that should not be used.

En lugar de:

 override fun toString (): String { return " hi " }

usar:

 override fun toString () = " hi "

7. If an argument list in a function declaration (including constructors) or function call contains more than two arguments, these arguments should be split by newlines in the following style.

Valid example:

 class Foo ( val a : String ,
         b : String ,
         val c : String ) {
}

fun foo (
       a : String ,
       b : String ,
       c : String
) {

}

If and only if the first parameter is on the same line as an opening parenthesis, all parameters can be horizontally aligned by the first parameter. Otherwise, there should be a line break after an opening parenthesis.

Kotlin 1.4 introduced a trailing comma as an optional feature, so it is generally recommended to place all parameters on a separate line and append trailing comma. It makes the resolving of merge conflicts easier.

Valid example:

 fun foo (
       a : String ,
       b : String ,
) {

}

same should be done for function calls/constructor arguments/etc

Kotlin supports trailing commas in the following cases:

Enumerations Value arguments Class properties and parameters Function value parameters Parameters with optional type (including setters) Indexing suffix Lambda parameters when entry Collection literals (in annotations) Type arguments Type parameters Destructuring declarations

8. If the supertype list has more than two elements, they should be separated by newlines.

Valid example:

 class MyFavouriteVeryLongClassHolder :
    MyLongHolder < MyFavouriteVeryLongClass >(),
    SomeOtherInterface ,
    AndAnotherOne { }

3.7 Using blank lines

Reduce unnecessary blank lines and maintain a compact code size. By reducing unnecessary blank lines, you can display more code on one screen, which improves code readability.

• Blank lines should separate content based on relevance and should be placed between groups of fields, constructors, methods, nested classes, init blocks, and objects (see 3.1.2).
• Do not use more than one line inside methods, type definitions, and initialization expressions.
• Generally, do not use more than two consecutive blank lines in a row.
• Do not put newlines in the beginning or end of code blocks with curly braces.

Valid example:

 fun baz () {

    doSomething()  // No need to add blank lines at the beginning and end of the code block
    // ...

}

3.8 Horizontal space

This section describes general rules and recommendations for using spaces in the code.

3.8.1: Usage of whitespace for code separation

Follow the recommendations below for using space to separate keywords:

Note: These recommendations are for cases where symbols are located on the same line. However, in some cases, a line break could be used instead of a space.

1. Separate keywords (such as if , when , for ) from the opening parenthesis with single whitespace. The only exception is the constructor keyword, which should not be separated from the opening parenthesis.

2. Separate keywords like else or try from the opening brace ( { ) with single whitespace. If else is used in a ternary-style statement without braces, there should be a single space between else and the statement after: if (condition) foo() else bar()

3. Use a single whitespace before all opening braces ( { ). The only exception is the passing of a lambda as a parameter inside parentheses:

    private fun foo ( a : ( Int ) -> Int , b : Int ) {}
    foo({x : Int -> x}, 5 ) // no space before '{'

4. Single whitespace should be placed on both sides of binary operators. This also applies to operator-like symbols. Por ejemplo:

• A colon in generic structures with the where keyword: where T : Type
• Arrow in lambdas: (str: String) -> str.length()

Exceptions:

• Two colons ( :: ) are written without spaces:
  Object::toString
• The dot separator ( . ) that stays on the same line with an object name:
  object.toString()
• Safe access modifiers ?. !! that stay on the same line with an object name:
  object?.toString()
• Operator .. for creating ranges:
  1..100

5. Use spaces after ( , ), ( : ), and ( ; ), except when the symbol is at the end of the line. However, note that this code style prohibits the use of ( ; ) in the middle of a line (see 3.3.2). There should be no whitespaces at the end of a line. The only scenario where there should be no space after a colon is when the colon is used in the annotation to specify a use-site target (for example, @param:JsonProperty ). There should be no spaces before , , : and ; .

   Exceptions for spaces and colons:

   • When : is used to separate a type and a supertype, including an anonymous object (after object keyword)
   • When delegating to a superclass constructor or different constructor of the same class

Valid example:

  abstract class Foo < out T : Any > : IFoo { }

  class FooImpl : Foo () {
      constructor (x : String ) : this (x) { /* ... */ }

      val x = object : IFoo { /* ... */ }
  }

6. There should be only one space between the identifier and its type: list: List<String> If the type is nullable, there should be no space before ? .

7. When using [] operator ( get/set ) there should be no spaces between identifier and [ : someList[0] .

8. There should be no space between a method or constructor name (both at declaration and at call site) and a parenthesis: foo() {} . Note that this sub-rule is related only to spaces; the rules for whitespaces are described in see 3.6.2. This rule does not prohibit, for example, the following code:

 fun foo
(
    a : String
)

9. Never put a space after ( , [ , < (when used as a bracket in templates) or before ) , ] , > (when used as a bracket in templates).

10. There should be no spaces between a prefix/postfix operator (like !! or ++ ) and its operand.

3.8.2: No spaces for horizontal alignment

Horizontal alignment refers to aligning code blocks by adding space to the code. Horizontal alignment should not be used because:

• When modifying code, it takes much time for new developers to format, support, and fix alignment issues.
• Long identifier names will break the alignment and lead to less presentable code.
• There are more disadvantages than advantages in alignment. To reduce maintenance costs, misalignment (???) is the best choice.

Recommendation: Alignment only looks suitable for enum class , where it can be used in table format to improve code readability:

 enum class Warnings ( private val id : Int , private val canBeAutoCorrected : Boolean , private val warn : String ) : Rule {
    PACKAGE_NAME_MISSING         ( 1 , true ,  " no package name declared in a file " ),
    PACKAGE_NAME_INCORRECT_CASE  ( 2 , true ,  " package name should be completely in a lower case " ),
    PACKAGE_NAME_INCORRECT_PREFIX ( 3 , false , " package name should start from the company's domain " )
    ;
}

Valid example:

 private val nr : Int // no alignment, but looks fine
private var color : Color // no alignment

Invalid example :

 private val    nr : Int    // aligned comment with extra spaces
private val color : Color  // alignment for a comment and alignment for identifier name

3.9 Enumerations

Enum values are separated by a comma and line break, with ';' placed on the new line.

1. The comma and line break characters separate enum values. Poner ; on the new line:

 enum class Warnings {
    A ,
    B ,
    C ,
    ;
}

This will help to resolve conflicts and reduce the number of conflicts during merging pull requests. Also, use trailing comma.

2. If the enum is simple (no properties, methods, and comments inside), you can declare it in a single line:

 enum class Suit { CLUBS , HEARTS , SPADES , DIAMONDS }

3. Enum classes take preference (if it is possible to use it). For example, instead of two boolean properties:

 val isCelsius = true
val isFahrenheit = false

use enum class:

 enum class TemperatureScale { CELSIUS , FAHRENHEIT }

• The variable value only changes within a fixed range and is defined with the enum type.
• Avoid comparison with magic numbers of -1, 0, and 1 ; use enums instead.

 enum class ComparisonResult {
    ORDERED_ASCENDING ,
    ORDERED_SAME ,
    ORDERED_DESCENDING ,
    ;
}

3.10 Variable declaration

This section describes rules for the declaration of variables.

3.10.1 Declare one variable per line

Each property or variable must be declared on a separate line.

Invalid example :

 val n1 : Int ; val n2 : Int 

3.10.2 Variables should be declared near the line where they are first used

Declare local variables close to the point where they are first used to minimize their scope. This will also increase the readability of the code. Local variables are usually initialized during their declaration or immediately after. The member fields of the class should be declared collectively (see Rule 3.1.2 for details on the class structure).

3.11 'When' expression

The when statement must have an 'else' branch unless the condition variable is enumerated or a sealed type. Each when statement should contain an else statement group, even if it does not contain any code.

Exception: If 'when' statement of the enum or sealed type contains all enum values, there is no need to have an "else" branch. The compiler can issue a warning when it is missing.

3.12 Annotations

Each annotation applied to a class, method or constructor should be placed on its own line. Consider the following examples:

1. Annotations applied to the class, method or constructor are placed on separate lines (one annotation per line).

Valid example :

@MustBeDocumented
@CustomAnnotation
fun getNameIfPresent () { /* ... */ }

2. A single annotation should be on the same line as the code it is annotating.

Valid example :

@CustomAnnotation class Foo {}

3. Multiple annotations applied to a field or property can appear on the same line as the corresponding field.

Valid example :

@MustBeDocumented @CustomAnnotation val loader : DataLoader

3.13 Block comments

Block comments should be placed at the same indentation level as the surrounding code. See examples below.

Valid example :

 class SomeClass {
    /*
     * This is
     * okay
     */
     fun foo () {}
}

Note : Use /*...*/ block comments to enable automatic formatting by IDEs.

3.14 Modifiers and constant values

This section contains recommendations regarding modifiers and constant values.

3.14.1 Declaration with multiple modifiers

If a declaration has multiple modifiers, always follow the proper sequence. Valid sequence:

public / internal / protected / private
expect / actual
final / open / abstract / sealed / const
external
override
lateinit
tailrec
crossinline
vararg
suspend
inner
out
enum / annotation
companion
inline / noinline
reified
infix
operator
data

3.14.2: Separate long numerical values with an underscore

An underscore character should separate long numerical values. Note: Using underscores simplifies reading and helps to find errors in numeric constants.

 val oneMillion = 1_000_000
val creditCardNumber = 1234_5678_9012_3456L
val socialSecurityNumber = 999_99_9999L
val hexBytes = 0xFF_EC_DE_5E
val bytes = 0b11010010_01101001_10010100_10010010 

3.14.3: Magic number

Prefer defining constants with clear names describing what the magic number means. Valid example :

 class Person () {
    fun isAdult ( age : Int ): Boolean = age >= majority

    companion object {
        private const val majority = 18
    }
}

Invalid example :

 class Person () {
    fun isAdult ( age : Int ): Boolean = age >= 18
}

3.15 Strings

This section describes the general rules of using strings.

3.15.1 Concatenation of Strings

String concatenation is prohibited if the string can fit on one line. Use raw strings and string templates instead. Kotlin has significantly improved the use of Strings: String templates, Raw strings. Therefore, compared to using explicit concatenation, code looks much better when proper Kotlin strings are used for short lines, and you do not need to split them with newline characters.

Invalid example :

 val myStr = " Super string "
val value = myStr + " concatenated "

Valid example :

 val myStr = " Super string "
val value = " $myStr concatenated " 

3.15.2 String template format

Redundant curly braces in string templates

If there is only one variable in a string template, there is no need to use such a template. Use this variable directly. Invalid example :

 val someString = " ${myArgument} ${myArgument.foo()} "

Valid example :

 val someString = " $myArgument ${myArgument.foo()} "

Redundant string template

In case a string template contains only one variable - there is no need to use the string template. Use this variable directly.

Invalid example :

 val someString = " $myArgument "

Valid example :

 val someString = myArgument

3.16 Conditional Statements

This section describes the general rules related to the сonditional statements.

3.16.1 Collapsing redundant nested if-statements

The nested if-statements, when possible, should be collapsed into a single one by concatenating their conditions with the infix operator &&.

This improves the readability by reducing the number of the nested language constructs.

Simple collapse

Invalid example :

 if (cond1) {
    if (cond2) {
        doSomething()
    }
}

Valid example :

 if (cond1 && cond2) {
    doSomething()
}

Compound conditions

Invalid example :

 if (cond1) {
    if (cond2 || cond3) {
        doSomething()
    }
}

Valid example :

 if (cond1 && (cond2 || cond3)) {
    doSomething()
}

3.16.2 Too complex conditions

Too complex conditions should be simplified according to boolean algebra rules, if it is possible. The following rules are considered when simplifying an expression:

• boolean literals are removed (eg foo() || false -> foo() )
• double negation is removed (eg !(!a) -> a )
• expression with the same variable are simplified (eg a && b && a -> a && b )
• remove expression from disjunction, if they are subset of other expression (eg a || (a && b) -> a )
• remove expression from conjunction, if they are more broad than other expression (eg a && (a || b) -> a )
• de Morgan's rule (negation is moved inside parentheses, ie !(a || b) -> !a && !b )

Valid example

 if (condition1 && condition2) {
    foo()
}

Invalid example

 if (condition1 && condition2 && condition1) {
    foo()
}

4. Variables and types

This section is dedicated to the rules and recommendations for using variables and types in your code.

4.1 Variables

The rules of using variables are explained in the below topics.

4.1.1 Do not use Float and Double types when accurate calculations are needed

Floating-point numbers provide a good approximation over a wide range of values, but they cannot produce accurate results in some cases. Binary floating-point numbers are unsuitable for precise calculations because it is impossible to represent 0.1 or any other negative power of 10 in a binary representation with a finite length.

The following code example seems to be obvious:

    val myValue = 2.0 - 1.1
    println (myValue)

However, it will print the following value: 0.8999999999999999

Therefore, for precise calculations (for example, in finance or exact sciences), using such types as Int , Long , BigDecimal are recommended. The BigDecimal type should serve as a good choice.

Invalid example : Float values containing more than six or seven decimal numbers will be rounded.

 val eFloat = 2.7182818284f // Float, will be rounded to 2.7182817

Valid example : (when precise calculations are needed):

   val income = BigDecimal ( " 2.0 " )
   val expense = BigDecimal ( " 1.1 " )
   println (income.subtract(expense)) // you will obtain 0.9 here 

4.1.2: Comparing numeric float type values

Numeric float type values should not be directly compared with the equality operator (==) or other methods, such as compareTo() and equals() . Since floating-point numbers involve precision problems in computer representation, it is better to use BigDecimal as recommended in Rule 4.1.1 to make accurate computations and comparisons. The following code describes these problems.

Invalid example :

 val f1 = 1.0f - 0.9f
val f2 = 0.9f - 0.8f
if (f1 == f2) {
   println ( " Expected to enter here " )
} else {
   println ( " But this block will be reached " )
}

val flt1 = f1;
val flt2 = f2;
if (flt1.equals(flt2)) {
   println ( " Expected to enter here " )
} else {
   println ( " But this block will be reached " )
}

Valid example :

 val foo = 1.03f
val bar = 0.42f
if (abs(foo - bar) > 1e - 6f ) {
    println ( " Ok " )
} else {
    println ( " Not " )
}

4.1.3 Try to use 'val' instead of 'var' for variable declaration [SAY_NO_TO_VAR]

Variables with the val modifier are immutable (read-only). Using val variables instead of var variables increases code robustness and readability. This is because var variables can be reassigned several times in the business logic. However, in some scenarios with loops or accumulators, only var s are permitted.

4.2 Types

This section provides recommendations for using types.

4.2.1: Use Contracts and smart cast as much as possible

The Kotlin compiler has introduced Smart Casts that help reduce the size of code.

Invalid example :

    if (x is String ) {
        print ((x as String ).length) // x was already automatically cast to String - no need to use 'as' keyword here
    }

Valid example :

    if (x is String ) {
        print (x.length) // x was already automatically cast to String - no need to use 'as' keyword here
    }

Also, Kotlin 1.3 introduced Contracts that provide enhanced logic for smart-cast. Contracts are used and are very stable in stdlib , for example:

 fun bar ( x : String? ) {
    if ( ! x.isNullOrEmpty()) {
        println ( " length of ' $x ' is ${x.length} " ) // smartcasted to not-null
    }
}

Smart cast and contracts are a better choice because they reduce boilerplate code and features forced type conversion.

Invalid example :

 fun String?. isNotNull (): Boolean = this != null

fun foo ( s : String? ) {
    if (s.isNotNull()) s !! .length // No smartcast here and !! operator is used
}

Valid example :

 fun foo ( s : String? ) {
    if (s.isNotNull()) s.length // We have used a method with contract from stdlib that helped compiler to execute smart cast
}

4.2.2: Try to use type alias to represent types making code more readable

Type aliases provide alternative names for existing types. If the type name is too long, you can replace it with a shorter name, which helps to shorten long generic types. For example, code looks much more readable if you introduce a typealias instead of a long chain of nested generic types. We recommend using a typealias if the type contains more than two nested generic types and is longer than 25 chars .

Invalid example :

 val b : MutableMap < String , MutableList < String >>

Valid example :

 typealias FileTable = MutableMap < String , MutableList < String >>
val b : FileTable

You can also provide additional aliases for function (lambda-like) types:

 typealias MyHandler = ( Int , String , Any ) -> Unit

typealias Predicate < T > = ( T ) -> Boolean

4.3 Null safety and variable declarations

Kotlin is declared as a null-safe programming language. However, to achieve compatibility with Java, it still supports nullable types.

4.3.1: Avoid declaring variables with nullable types, especially from Kotlin stdlib

To avoid NullPointerException and help the compiler prevent Null Pointer Exceptions, avoid using nullable types (with ? symbol).

Invalid example :

 val a : Int? = 0

Valid example :

 val a : Int = 0

Nevertheless, when using Java libraries extensively, you have to use nullable types and enrich the code with !! ? símbolos. Avoid using nullable types for Kotlin stdlib (declared in official documentation). Try to use initializers for empty collections. For example, if you want to initialize a list instead of null , use emptyList() .

Invalid example :

 val a : List < Int > ? = null

Valid example :

 val a : List < Int > = emptyList()

4.3.2: Variables of generic types should have an explicit type declaration

Like in Java, classes in Kotlin may have type parameters. To create an instance of such a class, we typically need to provide type arguments:

 val myVariable : Map < Int , String > = emptyMap< Int , String >()

However, the compiler can inherit type parameters from the r-value (value assigned to a variable). Therefore, it will not force users to declare the type explicitly. These declarations are not recommended because programmers would need to find the return value and understand the variable type by looking at the method.

Invalid example :

 val myVariable = emptyMap< Int , String >()

Valid example :

 val myVariable : Map < Int , String > = emptyMap()

4.3.3 Null-safety

Try to avoid explicit null checks (explicit comparison with null ) Kotlin is declared as Null-safe language. However, Kotlin architects wanted Kotlin to be fully compatible with Java; that's why the null keyword was also introduced in Kotlin.

There are several code-structures that can be used in Kotlin to avoid null-checks. For example: ?: , .let {} , .also {} , etc

Invalid example:

 // example 1
var myVar : Int? = null
if (myVar == null ) {
    println ( " null " )
    return
}

// example 2
if (myVar != null ) {
    println ( " not null " )
    return
}

// example 3
val anotherVal = if (myVar != null ) {
                     println ( " not null " )
                     1
                 } else {
                     2
                 }
// example 4
if (myVar == null ) {
    println ( " null " )
} else {
    println ( " not null " )
}

Valid example:

 // example 1
var myVar : Int? = null
myVar ? : run {
    println ( " null " )
    return
}

// example 2
myVar?. let {
    println ( " not null " )
    return
}

// example 3
val anotherVal = myVar?. also {
                     println ( " not null " )
                     1
                 } ? : 2

// example 4
myVar?. let {
    println ( " not null " )
} ? : run { println ( " null " ) }

Exceptions:

In the case of complex expressions, such as multiple else-if structures or long conditional statements, there is common sense to use explicit comparison with null .

Valid examples:

 if (myVar != null ) {
    println ( " not null " )
} else if (anotherCondition) {
    println ( " Other condition " )
}

 if (myVar == null || otherValue == 5 && isValid) {}

Please also note, that instead of using require(a != null) with a not null check - you should use a special Kotlin function called requireNotNull(a) .

5. Functions

This section describes the rules of using functions in your code.

5.1 Function design

Developers can write clean code by gaining knowledge of how to build design patterns and avoid code smells. You should utilize this approach, along with functional style, when writing Kotlin code. The concepts behind functional style are as follows: Functions are the smallest unit of combinable and reusable code. They should have clean logic, high cohesion , and low coupling to organize the code effectively. The code in functions should be simple and not conceal the author's original intentions.

Additionally, it should have a clean abstraction, and control statements should be used straightforwardly. The side effects (code that does not affect a function's return value but affects global/object instance variables) should not be used for state changes of an object. The only exceptions to this are state machines.

Kotlin is designed to support and encourage functional programming, featuring the corresponding built-in mechanisms. Also, it supports standard collections and sequences feature methods that enable functional programming (for example, apply , with , let , and run ), Kotlin Higher-Order functions, function types, lambdas, and default function arguments. As previously discussed, Kotlin supports and encourages the use of immutable types, which in turn motivates programmers to write pure functions that avoid side effects and have a corresponding output for specific input. The pipeline data flow for the pure function comprises a functional paradigm. It is easy to implement concurrent programming when you have chains of function calls, where each step features the following characteristics:

1. Sencillez
2. Verifiability
3. Probabilidad
4. Replaceability
5. Pluggability
6. Extensibilidad
7. Immutable results

There can be only one side effect in this data stream, which can be placed only at the end of the execution queue.

5.1.1 Avoid functions that are too long

The function should be displayable on one screen and only implement one certain logic. If a function is too long, it often means complex and could be split or simplified. Functions should consist of 30 lines (non-empty and non-comment) in total.

Exception: Some functions that implement complex algorithms may exceed 30 lines due to aggregation and comprehensiveness. Linter warnings for such functions can be suppressed .

Even if a long function works well, new problems or bugs may appear due to the function's complex logic once it is modified by someone else. Therefore, it is recommended to split such functions into several separate and shorter functions that are easier to manage. This approach will enable other programmers to read and modify the code properly.

5.1.2 Avoid deep nesting of function code blocks, limiting to four levels

The nesting depth of a function's code block is the depth of mutual inclusion between the code control blocks in the function (for example: if, for, while, and when). Each nesting level will increase the amount of effort needed to read the code because you need to remember the current "stack" (for example, entering conditional statements and loops). Exception: The nesting levels of the lambda expressions, local classes, and anonymous classes in functions are calculated based on the innermost function. The nesting levels of enclosing methods are not accumulated. Functional decomposition should be implemented to avoid confusion for the developer who reads the code. This will help the reader switch between contexts.

5.1.3 Avoid using nested functions

Nested functions create a more complex function context, thereby confusing readers. With nested functions, the visibility context may not be evident to the code reader.

Invalid example :

 fun foo () {
    fun nested (): String {
        return " String from nested function "
    }
    println ( " Nested Output: ${nested()} " )
}

5.1.4 Negated function calls

Don't use negated function calls if it can be replaced with negated version of this function

Invalid example :

 fun foo () {
    val list = listOf ( 1 , 2 , 3 )

    if ( ! list.isEmpty()) {
        // Some cool logic
    }
}

Valid example :

 fun foo () {
    val list = listOf ( 1 , 2 , 3 )

    if (list.isNotEmpty()) {
        // Some cool logic
    }
}

5.2 Function arguments

The rules for using function arguments are described in the below topics.

5.2.1 The lambda parameter of the function should be placed at the end of the argument list

With such notation, it is easier to use curly brackets, leading to better code readability.

Valid example :

 // declaration
fun myFoo ( someArg : Int , myLambda : () -> Unit ) {
// ...
}

// usage
myFoo( 1 ) {
println ( " hey " )
}

5.2.2 Number of function parameters should be limited to five

A long argument list is a code smell that leads to less reliable code. It is recommended to reduce the number of parameters. Having more than five parameters leads to difficulties in maintenance and conflicts merging. If parameter groups appear in different functions multiple times, these parameters are closely related and can be encapsulated into a single Data Class. It is recommended that you use Data Classes and Maps to unify these function arguments.

5.2.3 Use default values for function arguments instead of overloading them

In Java, default values for function arguments are prohibited. That is why the function should be overloaded when you need to create a function with fewer arguments. In Kotlin, you can use default arguments instead.

Invalid example :

 private fun foo ( arg : Int ) {
    // ...
}

private fun foo () {
    // ...
}

Valid example :

 private fun foo ( arg : Int = 0) {
     // ...
 }

5.2.4 Synchronizing code inside asynchronous code

Try to avoid using runBlocking in asynchronous code

Invalid example :

 GlobalScope .async {
    runBlocking {
        count ++
    }
}

5.2.5 Long lambdas should have explicit parameters

The lambda without parameters shouldn't be too long. If a lambda is too long, it can confuse the user. Lambda without parameters should consist of 10 lines (non-empty and non-comment) in total.

5.2.6 Avoid using unnecessary, custom label

Expressions with unnecessary, custom labels generally increase complexity and worsen the maintainability of the code.

Invalid example :

run lab@ {
    list.forEach {
        return @lab
    }
}

Valid example :

list.forEachIndexed { index, i ->
    return @forEachIndexed
}

lab@ for (i : Int in q) {
    for (j : Int in q) {
        println (i)
        break @lab
    }
}

6. Classes, interfaces, and extension functions

6.1 Classes

This section describes the rules of denoting classes in your code.

6.1.1 Denoting a class with a single constructor

When a class has a single constructor, it should be defined as a primary constructor in the declaration of the class. If the class contains only one explicit constructor, it should be converted to a primary constructor.

Invalid example :

 class Test {
    var a : Int
    constructor (a : Int ) {
        this .a = a
    }
}

Valid example :

 class Test ( var a : Int ) {
    // ...
}

// in case of any annotations or modifiers used on a constructor:
class Test private constructor( var a : Int ) {
    // ...
}

6.1.2 Prefer data classes instead of classes without any functional logic

Some people say that the data class is a code smell. However, if you need to use it (which makes your code more simple), you can utilize the Kotlin data class . The main purpose of this class is to hold data, but also data class will automatically generate several useful methods:

• equals()/hashCode() pair;
• toString ()
• componentN() functions corresponding to the properties in their order of declaration;
• copy() function

Therefore, instead of using normal classes:

 class Test {
    var a : Int = 0
        get() = field
        set(value : Int ) { field = value}
}

class Test {
    var a : Int = 0
    var b : Int = 0

    constructor (a : Int , b : Int ) {
        this .a = a
        this .b = b
    }
}

// or
class Test ( var a : Int = 0 , var b : Int = 0 )

// or
class Test () {
    var a : Int = 0
    var b : Int = 0
}

prefer data classes:

 data class Test1 ( var a : Int = 0 , var b : Int = 0 )

Exception 1 : Note that data classes cannot be abstract, open, sealed, or inner; that is why these types of classes cannot be changed to a data class.

Exception 2 : No need to convert a class to a data class if this class extends some other class or implements an interface.

6.1.3 Do not use the primary constructor if it is empty or useless

The primary constructor is a part of the class header; it is placed after the class name and type parameters (optional) but can be omitted if it is not used.

Invalid example :

 // simple case that does not need a primary constructor
class Test () {
    var a : Int = 0
    var b : Int = 0
}

// empty primary constructor is not needed here
// it can be replaced with a primary contructor with one argument or removed
class Test () {
    var a  = " Property "

    init {
        println ( " some init " )
    }

    constructor (a : String ) : this () {
        this .a = a
    }
}

Valid example :

 // the good example here is a data class; this example also shows that you should get rid of braces for the primary constructor
class Test {
    var a : Int = 0
    var b : Int = 0
}

6.1.4 Do not use redundant init blocks in your class

Several init blocks are redundant and generally should not be used in your class. The primary constructor cannot contain any code. That is why Kotlin has introduced init blocks. These blocks store the code to be run during the class initialization. Kotlin allows writing multiple initialization blocks executed in the same order as they appear in the class body. Even when you follow (rule 3.2)[#r3.2], this makes your code less readable as the programmer needs to keep in mind all init blocks and trace the execution of the code. Therefore, you should try to use a single init block to reduce the code's complexity. If you need to do some logging or make some calculations before the class property assignment, you can use powerful functional programming. This will reduce the possibility of the error if your init blocks' order is accidentally changed and make the code logic more coupled. It is always enough to use one init block to implement your idea in Kotlin.

Invalid example :

 class YourClass ( var name : String ) {
    init {
        println ( " First initializer block that prints ${name} " )
    }

    val property = " Property: ${name.length} " . also (::println)

    init {
        println ( " Second initializer block that prints ${name.length} " )
    }
}

Valid example :

 class YourClass ( var name : String ) {
    init {
        println ( " First initializer block that prints ${name} " )
    }

    val property = " Property: ${name.length} " . also { prop ->
        println (prop)
        println ( " Second initializer block that prints ${name.length} " )
    }
}

The init block was not added to Kotlin to help you initialize your properties; it is needed for more complex tasks. Therefore if the init block contains only assignments of variables - move it directly to properties to be correctly initialized near the declaration. In some cases, this rule can be in clash with 6.1.1, but that should not stop you.

Invalid example :

 class A ( baseUrl : String ) {
    private val customUrl : String
    init {
        customUrl = " $baseUrl /myUrl "
    }
}

Valid example :

 class A ( baseUrl : String ) {
    private val customUrl = " $baseUrl /myUrl "
}

6.1.5 Explicit supertype qualification

The explicit supertype qualification should not be used if there is no clash between called methods. This rule is applicable to both interfaces and classes.

Invalid example :

 open class Rectangle {
    open fun draw () { /* ... */ }
}

class Square () : Rectangle() {
    override fun draw () {
        super < Rectangle >.draw() // no need in super<Rectangle> here
    }
}

6.1.6 Abstract class should have at least one abstract method

Abstract classes are used to force a developer to implement some of its parts in their inheritors. When the abstract class has no abstract methods, it was set abstract incorrectly and can be converted to a regular class.

Invalid example :

 abstract class NotAbstract {
    fun foo () {}

    fun test () {}
}

Valid example :

 abstract class NotAbstract {
    abstract fun foo ()

    fun test () {}
}

// OR
class NotAbstract {
    fun foo () {}

    fun test () {}
}

6.1.7 When using the "implicit backing property" scheme, the name of real and back property should be the same

Kotlin has a mechanism of backing properties. In some cases, implicit backing is not enough and it should be done explicitly:

 private var _table : Map < String , Int > ? = null
val table : Map < String , Int >
    get() {
        if ( _table == null ) {
            _table = HashMap () // Type parameters are inferred
        }
        return _table ? : throw AssertionError ( " Set to null by another thread " )
    }

In this case, the name of the backing property ( _table ) should be the same as the name of the real property ( table ) but should have an underscore ( _ ) prefix. It is one of the exceptions from the identifier names rule

6.1.8 Avoid using custom getters and setters

Kotlin has a perfect mechanism of properties. Kotlin compiler automatically generates get and set methods for properties and can override them.

Invalid example:

 class A {
    var size : Int = 0
        set(value) {
            println ( " Side effect " )
            field = value
        }
        // user of this class does not expect calling A.size receive size * 2
        get() = field * 2
}

From the callee code, these methods look like access to this property: A().isEmpty = true for setter and A().isEmpty for getter.

However, when get and set are overridden, it isn't very clear for a developer who uses this particular class. The developer expects to get the property value but receives some unknown value and some extra side-effect hidden by the custom getter/setter. Use extra functions instead to avoid confusion.

Valid example :

 class A {
    var size : Int = 0
    fun initSize ( value : Int ) {
        // some custom logic
    }

    // this will not confuse developer and he will get exactly what he expects
    fun goodNameThatDescribesThisGetter () = this .size * 2
}

Exception: Private setters are only exceptions that are not prohibited by this rule.

6.1.9 Never use the name of a variable in the custom getter or setter (possible_bug)

If you ignored recommendation 6.1.8, be careful with using the name of the property in your custom getter/setter as it can accidentally cause a recursive call and a StackOverflow Error . Use the field keyword instead.

Invalid example (very bad) :

 var isEmpty : Boolean
    set(value) {
        println ( " Side effect " )
        isEmpty = value
    }
    get() = isEmpty

6.1.10 No trivial getters and setters are allowed in the code

In Java, trivial getters - are the getters that are just returning the field value. Trivial setters - are merely setting the field with a value without any transformation. However, in Kotlin, trivial getters/setters are generated by default. There is no need to use it explicitly for all types of data structures in Kotlin.

Invalid example :

 class A {
    var a : Int = 0
    get() = field
    set(value : Int ) { field = value }

    //
}

Valid example :

 class A {
    var a : Int = 0
    get() = field
    set(value : Int ) { field = value }

    //
}

6.1.11 Use 'apply' for grouping object initialization

In Java, before functional programming became popular, many classes from common libraries used the configuration paradigm. To use these classes, you had to create an object with the constructor with 0-2 arguments and set the fields needed to run the object. In Kotlin, to reduce the number of dummy code line and to group objects apply extension was added:

Invalid example :

 class HttpClient ( var name : String ) {
    var url : String = " "
    var port : String = " "
    var timeout = 0

    fun doRequest () {}
}

fun main () {
    val httpClient = HttpClient ( " myConnection " )
    httpClient.url = " http://example.com "
    httpClient.port = " 8080 "
    httpClient.timeout = 100

    httpCLient.doRequest()
}

Valid example :

 class HttpClient ( var name : String ) {
    var url : String = " "
    var port : String = " "
    var timeout = 0

    fun doRequest () {}
}

fun main () {
    val httpClient = HttpClient ( " myConnection " )
            . apply {
                url = " http://example.com "
                port = " 8080 "
                timeout = 100
            }
    httpClient.doRequest()
}

6.1.12 Prefer Inline classes when a class has a single property

If a class has only one immutable property, then it can be converted to the inline class.

Sometimes it is necessary for business logic to create a wrapper around some type. However, it introduces runtime overhead due to additional heap allocations. Moreover, if the wrapped type is primitive, the performance hit is terrible, because primitive types are usually heavily optimized by the runtime, while their wrappers don't get any special treatment.

Invalid example :

 class Password {
    val value : String
}

Valid example :

 inline class Password ( val value : String )

6.2 Extension functions

This section describes the rules of using extension functions in your code.

Extension functions is a killer-feature in Kotlin. It gives you a chance to extend classes that were already implemented in external libraries and helps you to make classes less heavy. Extension functions are resolved statically.

6.2.1 Use extension functions for making logic of classes less coupled

It is recommended that for classes, the non-tightly coupled functions, which are rarely used in the class, should be implemented as extension functions where possible. They should be implemented in the same class/file where they are used. This is a non-deterministic rule, so the code cannot be checked or fixed automatically by a static analyzer.

6.2.2 No extension functions with the same name and signature if they extend base and inheritor classes (possible_bug)

You should avoid declaring extension functions with the same name and signature if their receivers are base and inheritor classes (possible_bug), as extension functions are resolved statically. There could be a situation when a developer implements two extension functions: one is for the base class and another for the inheritor. This can lead to an issue when an incorrect method is used.

Invalid example :

 open class A
class B : A ()

// two extension functions with the same signature
fun A. foo () = " A "
fun B. foo () = " B "

fun printClassName ( s : A ) { println (s.foo()) }

// this call will run foo() method from the base class A, but
// programmer can expect to run foo() from the class inheritor B
fun main () { printClassName( B ()) }

6.2.3 Don't use extension functions for the class in the same file

You should not use extension functions for the class in the same file, where it is defined.

Invalid example :

 class SomeClass {

}

fun SomeClass. deleteAllSpaces () {

}

6.2.4 Use 'lastIndex' in case you need to get latest element of a collection

You should not use property length with operation - 1, you can change this to lastIndex

Invalid example :

 val A = " name "
val B = A .length - 1
val C = A [ A .length - 1 ]

Valid example :

 val A = " name "
val B = A .lastIndex
val C = A [ A .lastIndex]

6.3 Interfaces

An Interface in Kotlin can contain declarations of abstract methods, as well as method implementations. What makes them different from abstract classes is that interfaces cannot store state. They can have properties, but these need to be abstract or to provide accessor implementations.

Kotlin's interfaces can define attributes and functions. In Kotlin and Java, the interface is the main presentation means of application programming interface (API) design and should take precedence over the use of (abstract) classes.

6.4 Objects

This section describes the rules of using objects in code.

6.4.1 Instead of using utility classes/objects, use extensions

Avoid using utility classes/objects; use extensions instead. As described in 6.2 Extension functions, using extension functions is a powerful method. This enables you to avoid unnecessary complexity and class/object wrapping and use top-level functions instead.

Invalid example :

 object StringUtil {
    fun stringInfo ( myString : String ): Int {
        return myString.count{ " something " .contains(it) }
    }
}
StringUtil .stringInfo( " myStr " )

Valid example :

 fun String. stringInfo (): Int {
    return this .count{ " something " .contains(it) }
}

" myStr " .stringInfo()

6.4.2 Objects should be used for Stateless Interfaces

Kotlin's objects are extremely useful when you need to implement some interface from an external library that does not have any state. There is no need to use classes for such structures.

Valid example :

 interface I {
    fun foo()
}

object O: I {
    override fun foo() {}
}

6.5 Kts Files

This section describes general rules for .kts files

6.5.1 kts files should wrap logic into top-level scope

It is still recommended wrapping logic inside functions and avoid using top-level statements for function calls or wrapping blocks of code in top-level scope functions like run .

Valid example :

 run {
    // some code
}

fun foo() {

}