Geekly articles weekly

Guía de estilo de Google en C ++. Parte 9

Parte 1. Introducción
...
Parte 8. Nombramiento
Parte 9. Comentarios
...


Este artículo es una traducción de parte de la guía de estilo de Google en C ++ al ruso.
Artículo original (fork en github), traducción actualizada .

Comentarios


Se requieren comentarios para el código (si planea leerlo). Las siguientes reglas describen lo que debe comentar y cómo. Pero recuerde: aunque los comentarios son muy importantes, el código perfecto es autodocumentarse. El uso de nombres "parlantes" para tipos y variables es mucho mejor que los nombres oscuros, que luego deben escribirse en los comentarios.

Comente el código en función de sus siguientes lectores: programadores que necesitan comprender su código. ¡Tenga en cuenta que puede ser el próximo lector!

Estilo de comentario


Use // o / * * / hasta que se viole la uniformidad.

Puede usar // o / ** / , sin embargo // es mucho preferible. Sin embargo, siempre alinee su estilo de comentario con el código existente.

Comentarios en el encabezado del archivo


Inserte un encabezado de licencia en la parte superior de cada archivo.

Los comentarios en el archivo deben describir su contenido. Si el archivo declara, describe o prueba una abstracción (para la cual ya hay un comentario), no es necesaria una descripción adicional en el encabezado del archivo. De lo contrario, inserte una descripción del contenido en la parte superior del archivo.

Información legal y lista de autores


Cada archivo debe contener información de licencia. El formato de la descripción depende de la licencia utilizada en el proyecto. Cada licencia (Apache 2.0, BSD, LGPL, GPL, etc.) puede tener sus propios requisitos de diseño.

Si realiza cambios significativos en el archivo, considere eliminar la lista anterior de autores. Los archivos actualizados ya no pueden contener una mención de derechos de autor y una lista de autores.

Contenido del archivo


Si .h declara varias abstracciones, el comentario en el encabezado del archivo generalmente debe describir el contenido del archivo y cómo las abstracciones están relacionadas entre sí. Una, dos oraciones en un comentario suelen ser suficientes. Se firma información más detallada en otro lugar (no en el encabezado del archivo).

No duplique comentarios en archivos .h y .cc : los comentarios se vuelven diferentes con el tiempo.

Comentarios de clase


Cada declaración de clase (excepto las muy obvias) debe ir acompañada de un comentario, para qué sirve la clase y cómo usarla.

//   GargantuanTable. // : // GargantuanTableIterator* iter = table->NewIterator(); // for (iter->Seek("foo"); !iter->done(); iter->Next()) { // process(iter->key(), iter->value()); // } // delete iter; class GargantuanTableIterator { ... };

El comentario sobre la clase debería ser suficiente para comprender: cómo y cuándo usar la clase, requisitos adicionales para el uso correcto de la clase. Describa, si es necesario, restricciones (supuestos) sobre la sincronización en la clase. Si se puede utilizar una instancia de la clase desde diferentes subprocesos, asegúrese de anotar las reglas de subprocesos múltiples.

También puede proporcionar ejemplos de código corto en el comentario de la clase para mostrar qué tan fácil es usar la clase.

Normalmente, una clase se declara / define en diferentes archivos ( .h y .cc ). Los comentarios que describen el uso de la clase deben estar al lado de la definición de la interfaz. Los comentarios sobre las complejidades de la implementación deben estar cerca del código de los métodos mismos.

Comentarios de funciones


Los comentarios sobre una declaración de función deben describir el uso de la función (excepto en los casos más obvios). Los comentarios sobre la definición de la función describen la implementación.

Declaración de funciones


La declaración de cada función debe tener un comentario (justo antes de la declaración), qué hace la función y cómo usarla. Un comentario puede omitirse solo si la función es simple y su uso es obvio (por ejemplo, la función de restar valores variables). Intente iniciar comentarios en el modo indicativo ("Abrir archivo"). No se recomienda utilizar el estado de ánimo imperativo ("Abrir archivo"). Un comentario describe la esencia de una función, no cómo lo hace.

En el comentario sobre la declaración de función, tenga en cuenta lo siguiente:

  • Lo que se alimenta a la entrada de la función, que se devuelve como resultado.
  • Para una función miembro de una clase: ¿la instancia mantiene argumentos de referencia,
    ¿Necesito liberar memoria?
  • ¿La función asigna la memoria que el código de llamada debe eliminar?
  • ¿Puede haber argumentos nullptr?
  • La complejidad de la función (algorítmica).
  • ¿Se permiten llamadas de diferentes hilos al mismo tiempo? ¿Qué pasa con la sincronización?

Un ejemplo:

 //    .    //   .    //    GargantuanTable  . // //      . // //    : // Iterator* iter = table->NewIterator(); // iter->Seek(""); // return iter; //         , //    NewIterator()     . Iterator* GetIterator() const;

Sin embargo, no mastique cosas obvias.

Al documentar funciones sobrecargadas, realice los principales cambios obstinados en comparación con la función original. Y si no hay cambios (lo que sucede a menudo), entonces no se necesitan comentarios adicionales.

Al comentar sobre constructores y destructores, tenga en cuenta que el lector de código conoce su propósito. Por lo tanto, el comentario del tipo "destruye este objeto" es estúpido. Puede describir lo que hace el constructor con argumentos (por ejemplo, cambiar la propiedad de los punteros) o qué tipo de operaciones de limpieza realiza el destructor. Si todo está claro, no comente nada. En general, los destructores generalmente no tienen comentarios (cuando se declaran).

Definición de función


Si hay algún truco en la implementación de la función, puede agregar un comentario explicativo a la definición. En él puede describir trucos con el código, dar una visión general de todas las etapas de los cálculos, explicar la elección de esta o aquella implementación (especialmente si hay mejores alternativas). Puede describir los principios de sincronización de código (aquí bloqueamos, pero aquí envolvemos el pescado).

Tenga en cuenta que no debe repetir el comentario sobre la declaración de la función (desde un archivo .h o similar). Es posible describir brevemente lo que hace la función, pero lo principal debería ser cómo lo hace.

Comentarios sobre variables


En el buen sentido, el nombre de la variable debe decir de inmediato qué es y por qué, sin embargo, en algunos casos, se requieren comentarios adicionales.

Miembro de datos de clase


El propósito de cada miembro de la clase debe ser obvio. Si hay sutilezas no obvias (significados especiales, vínculos con otros miembros, restricciones en la vida útil), todo esto debe ser comentado. Sin embargo, si el tipo y el nombre son suficientes, no necesita agregar comentarios.

Por otro lado, las descripciones de valores especiales (y no obvios) (nullptr o -1) serán útiles. Por ejemplo:

 private: //       // -1 - ,         int num_total_entries_;

Variables globales


Todas las variables globales deben comentarse sobre su propósito y (si no es obvio) por qué deberían ser globales. Por ejemplo:

 //   ,     const int kNumTestCases = 6;

Comentarios sobre la implementación


Comente sobre la implementación de una función o algoritmo en el caso de piezas de código no obvias, interesantes e importantes.

Comentarios descriptivos


Los bloques de código que son complejos o no estándar deben ir precedidos de un comentario. Por ejemplo:

 //    2.  x    for (int i = 0; i < result->size(); ++i) { x = (x << 8) + (*result)[i]; (*result)[i] = x >> 1; x &= 1; }

Comentarios de linea


Es recomendable complementar las líneas de código con un significado no obvio con un comentario (generalmente ubicado al final de la línea). Este comentario debe estar separado del código por 2 espacios. Por ejemplo:

 //   ,    mmap_budget = max<int64>(0, mmap_budget - index_->length()); if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) return; //

Tenga en cuenta que hay 2 comentarios en el bloque de código: uno describe lo que hace el código, el otro recuerda que el error ya está en el registro si hay un retorno de la función.

Comentarios sobre argumentos de funciones


Cuando asignar un argumento a una función no es obvio, considere las siguientes opciones:

  • Si el argumento es un valor fijo (constante literal) y ese valor
    usado en diferentes bloques de código (y se entiende que este valor es lo mismo)
    debes crear una constante y usarla explícitamente.
  • Tal vez deberías reemplazar el argumento de tipo bool con
    enumeración enumeración. Esto hará que el argumento sea autodeterminado.
  • Para las funciones que usan varias opciones de configuración en los argumentos, puede
    cree una clase (o estructura) separada que combine todas las opciones. Y pasar a funcionar
    Una instancia de esta clase.
    Este enfoque tiene varias ventajas: las opciones se indican mediante nombres, lo que explica
    Su propósito. El número de argumentos en la función se reduce: el código es más fácil de escribir y leer.
    Y si necesita agregar más opciones, no tendrá que cambiar la función llamada en sí.
  • En lugar de expresiones complejas en argumentos, use una variable intermedia a la que asigne una expresión.
  • Como último recurso, escriba comentarios en el lugar de la llamada para aclarar el propósito de los argumentos.

Considere los siguientes ejemplos:

 //    ? const DecimalNumber product = CalculateProduct(values, 7, false, nullptr);

Intentemos peinar el código:

 ProductOptions options; options.set_precision_decimals(7); options.set_use_cache(ProductOptions::kDontUseCache); const DecimalNumber product = CalculateProduct(values, options, /*completion_callback=*/nullptr);

Que no hacer


No explique lo obvio. En particular, no hay necesidad de explicar cosas que son obvias para una persona que conoce C ++. En cambio, puede describir por qué este código lo hace (o incluso hacer que el código se autodescriba).

Compara:

 //    . <-- :  ! auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); }

Con esto:

 //  (Process) "element"     auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); }

El código de autodescripción no necesita comentarios en absoluto.
El comentario sobre el código anterior puede ser generalmente obvio (y no necesario):

 if (!IsAlreadyProcessed(element)) { Process(element); }

Puntuación, ortografía y gramática


Presta atención a la puntuación, la ortografía y la gramática: es mucho más fácil leer los comentarios escritos correctamente.

Los comentarios deben escribirse como una historia: con la disposición correcta de mayúsculas y signos de puntuación. En la mayoría de los casos, las oraciones completas son más fáciles de entender que los fragmentos de frases. Los comentarios breves, como línea por línea, pueden ser menos formales, pero deben seguir un estilo común.

Aunque el énfasis excesivo del revisor de código en el uso de comas en lugar de punto y coma puede ser un poco molesto, es importante mantener un alto nivel de legibilidad y comprensión. La puntuación adecuada, la ortografía y la gramática contribuyen en gran medida a esto.

Comentarios TODO


Utilice TODO comentarios para un código temporal o una solución suficientemente buena (intermedia, no perfecta).

El comentario debe incluir la cadena TODO (todas las letras mayúsculas), seguido del nombre, la dirección de correo electrónico, la identificación del defecto u otra información para identificar al desarrollador y la naturaleza del problema para el que está escrito TODO . El propósito de esta descripción es poder encontrar más detalles más adelante. TODO con la descripción no significa que el programador especificado solucionará el problema. Por lo tanto, cuando crea TODO , el nombre habitual es su nombre.

 // TODO(kl@gmail.com):  "*"  . // TODO(Zeke)   . // TODO(bug 12345):   " ".

Si su TODO se ve como "Hagámoslo de manera diferente en el futuro", indique una fecha específica ("Correcto en noviembre de 2005") o un evento ("Elimine ese código cuando todos los clientes procesen solicitudes XML").

Nota:
- Los enlaces pueden conducir a secciones del manual que aún no se han traducido.
- una discusión de temas generales se realiza mejor en la Parte 1. Introducción

Source: https://habr.com/ru/post/480424/

More articles:


All Articles