Escribir especificaciones explícitas
Después de dividir una característica en partes, escriba cada pieza como una especificación explícita. Una especificación explícita no deja ambigüedad sobre lo que el código debe hacer, por lo que un lector, humano o ia, puede implementarlo sin adivinar.
Reemplazar palabras vagas por detalles explícitos
Compara dos descripciones de la misma función.
Impreciso: "Validar una contraseña."
Esta descripción deja abierto el número de caracteres necesarios, si se requieren letras mayúsculas y qué caracteres especiales se permiten.
Explícito: "Validar una contraseña: debe tener al menos 8 caracteres e incluir al menos una letra mayúscula, un número y un carácter especial (!@#$%)."
La versión explícita responde a cada una de esas preguntas.
Incluir cuatro partes
Una buena especificación indica:
- Entrada: qué datos recibe la función.
- Procesamiento: qué hace la función con los datos.
- Salida: lo que devuelve la función.
- Errores: qué problemas pueden producirse y cómo los gestiona la función.
Ejemplo: validar una dirección de correo electrónico
La especificación siguiente incluye las cuatro partes y agrega ejemplos:
Function: validate_email
Input: a string that might be an email address
Processing:
1. Check that the string has exactly one @ symbol.
2. Check that at least one character comes before the @.
3. Check that at least one dot comes after the @.
4. Check that at least 2 characters come after the last dot.
Output: True if all checks pass, False otherwise
Errors: If the input is None or not a string, return False.
Examples:
validate_email("user@example.com") → True
validate_email("invalid@") → False
validate_email("no-at-sign.com") → False
Un desarrollador o un asistente de IA pueden implementar esta función exactamente como se describe.
Ejemplo: calcular un descuento
Vago: "Aplicar un descuento."
Explícito:
Function: apply_discount
Input:
- original_price: a number (the price before the discount)
- discount_percent: a number (for example, 10 means 10% off)
Processing:
1. Calculate the discount amount: original_price × (discount_percent ÷ 100)
2. Subtract the discount amount from the original price.
Output: the final price after the discount
Errors:
- If discount_percent is less than 0 or greater than 100, return an error message.
- If original_price is less than 0, return an error message.
Examples:
apply_discount(100, 20) → 80
apply_discount(50, 0) → 50
apply_discount(100, -10) → error: discount must be from 0 through 100
Esta especificación indica la fórmula, los intervalos válidos y el resultado esperado para cada caso.
Por qué esto es importante para la inteligencia artificial
Si pide a un asistente de IA que "aplique un descuento", debe decidir cómo controlar porcentajes negativos, si se deben validar las entradas y qué fórmula usar. Una especificación explícita responde a esas preguntas de antemano.
La especificación también sirve para otros dos propósitos:
- Esto guía la implementación.
- Sus ejemplos se convierten en una lista de verificación de prueba. Puede comprobar si el código devuelve el resultado esperado para cada uno.
Una especificación describe lo que hace el código, no cómo escribirlo. Sea específico, incluya ejemplos y quite la ambigüedad.