Directrices de codificación de Bitxor

Regiones

En archivos largos, usamos las etiquetas region y endregion para agrupar el código relacionado. Esto hace que estos archivos sean más fáciles de navegar.

Las etiquetas región siempre deben estar rodeadas de líneas en blanco con una excepción. Si son la primera línea de un nuevo nivel de sangría, no se requiere una línea en blanco anterior. Las etiquetas endregion siempre deben estar rodeadas de líneas en blanco.

Por ejemplo,

class Something:
    # region load

    ...

    # endregion

    # region save

    ...

    # endregion

Examen de la unidad

Preferimos estructurar las pruebas unitarias en el formato Organizar/Actuar/Afirmar para delinear claramente el código bajo prueba y las afirmaciones que se prueban. Las pruebas unitarias deben contener comentarios que dividan las pruebas en las tres secciones cuando estén presentes. Esto es algo así como una decisión de juicio, ya que algunas pruebas no tendrán las tres secciones. For example,

# Arrange:
wordlist = ['alpha', 'beta', 'gamma', 'delta', 'epsilon', 'eta', 'theta', 'iota', 'kappa', 'lambda']
encoder = WordEncoder(wordlist)

# Act:
words = encoder.encode(0)

# Assert:
self.assertEqual(['alpha'], words)

Para una discusión más detallada, revise esta publicación de blog: https://bitxorblog.com/developer-guides/how-to-write-good-unit-tests.

Comentarios / Documentación

Incluya una declaración de derechos de autor en la parte superior de cada archivo. Para nuevos proyectos, utilice los contenidos de derechos de autor predeterminados. Se debe renunciar a los derechos de autor y todos los derechos relacionados para todas las contribuciones y a través de CC0 para todos los trabajos escritos.

Documentamos todos los métodos y clases públicos con al menos una oración o dos. Para proyectos destinados a ser utilizados como bibliotecas por desarrolladores externos, como SDK, se recomienda documentar todos los parámetros. Para otros proyectos, a menudo basta con hacer referencia a los parámetros sin documentar cada uno en detalle.

Creemos que el código debe ser en su mayor parte autodocumentado, así que use los comentarios en línea con moderación. Prefiera un código bien estructurado y buenos nombres a los comentarios en línea. Por ejemplo, en lugar de usar comentarios para delinear los pasos de un proceso complicado, preferimos refactorizar el código para tener una función bien nombrada por paso. Los comentarios en línea se pueden usar cuando el propósito del código no es inmediatamente claro para el lector.

Denominación

Evite nombres y abreviaturas impronunciables. ¡Usa un corrector ortográfico! Se recomienda codespell.

1. Los tipos definidos por el usuario (class, struct, enum) deben ser UpperCamelCase y ser sustantivos. [p.ej. MiEnum, PuntoEndNode]

2. Los nombres de las funciones deben contener verbos [p. ej. HazAlgo, ``IntentaHacerAlgo`]

   Las funciones que fallan al lanzar excepciones deben nombrarse de manera optimista [p. HazAlgo].

   Las funciones que fallan al devolver códigos de error deben tener el prefijo Try para indicar que la persona que llama debe verificar algo [p. PruebaHacerAlgo].

3. Las propiedades booleanas generalmente deben comenzar con is, has o should.

   isOpen() en lugar de open()

4. Las propiedades no booleanas generalmente deben evitar los prefijos get y set:

   value(12) en lugar de setValue(12)

   valor() en lugar de getValue()

Inicio sesión

No todos los marcos admiten el espectro completo de niveles de registro. A continuación, se incluye una descripción de los niveles de registro de mayor a menor gravedad:

• FATAL - Error crítico que requerirá la salida inmediata del programa.

• ERROR: error grave sobre el que el operador del nodo podría tener que actuar pero que no terminará el programa.

• ADVERTENCIA: error del cual el operador del nodo debe ser consciente pero es poco probable que requiera acción.

• IMPORTANTE - Mensaje informativo con énfasis adicional.

• INFO - Mensaje informativo registrado por defecto.

• DEBUG: mensaje informativo detallado que podría estar deshabilitado de forma predeterminada.

• TRACE: información de depuración de bajo nivel que casi siempre estará deshabilitada.

Espaciado Vertical

Generalmente, debe haber una línea en blanco después de cualquier desangrado. Una excepción es el cierre de llaves.

Por ejemplo,

if token:
    return token  # next line de-indents so should be blank

return {
    'token': token  # next line closes the prior brace, so shouldn't be blank
}

Recorte los espacios en blanco finales de todas las líneas. Termina cada archivo con una nueva línea.

Longitud de línea horizontal

La longitud máxima de línea es de 140 caracteres.

Espaciado de tokens

• Always put a space after commas �?�? like:

  outputAsciiString(buffer, something, elsewhere);
  

  No:

  outputAsciiString(buffer,something,elsewhere);
  

• Siempre ponga un espacio después de punto y coma �?�?en para, eso está bien:

  for (size_t j = 0; j < foo.size() - 1; ++j)
  

  Este no es:

  for (size_t j = 0;j < sections.size();++j)
  

for (size_t j = 0; j < foo.size() - x * 4; ++j)

for (size_t j=0; j<foo.size()-x*4; ++j)

Guías específicas del idioma