En mi artículo anterior, , exploramos cómo construir una herramienta CLI desde el principio. Ahora, tomemos el siguiente paso - ¿cómo lo haces bien? En última instancia, la clave está en la facilidad de uso. Un CLI bien diseñado se siente intuitivo, predecible y eficiente para el usuario. Sin embargo, esta facilidad de uso se logra a través de varios principios de diseño distintos, que exploraremos en este artículo. Dominar el arte de la línea de mando: tu guía final para desarrollar herramientas poderosas Dominar el arte de la línea de mando: tu guía final para desarrollar herramientas poderosas Para la demostración se utilizará el , pero los principios se aplican a casi cualquier marco CLI que pueda utilizar. Clica en la biblioteca de Python Parámetros La mayoría de las herramientas CLI aceptan la entrada del usuario. En la mayoría de los casos, esta entrada no es interactiva - viene en forma de Esto define cómo funciona la herramienta. parameters Por ejemplo, el El comando tiene al menos dos parámetros: cp 
 
 
 El camino al archivo o directorio a copiar, y El camino hacia el destino. También puede aceptar parámetros opcionales como que permiten la expansión verbal. -v En general, existen dos tipos de parámetros: y En la mayoría de las bibliotecas CLI, los parámetros requeridos se llaman (o argumentos de posición), y los parámetros opcionales se denominan . required optional arguments options Argumentos positivos Como su nombre sugiere, El usuario proporciona los valores en un orden específico, y la herramienta los interpreta en consecuencia. positional arguments Por ejemplo, si el El comando espera dos argumentos de posición - y El usuario lo llamaría como: cp fuente Destino cp source destination
 Incluso si su herramienta requiere entrada, a menudo es complicado (y innecesario) hacer que los usuarios especifiquen cada valor manualmente. . if you can provide a sensible default, make it an option instead of an argument Por ejemplo, a Los parámetros pueden defecar Forzar a los usuarios a recordar la posición y transmitir siempre la información no agrega valor, solo agrega fricción. --log-level info Múltiples argumentos A veces una herramienta puede necesitar para un solo argumento. Un ejemplo común es especificar varios archivos de origen para copiar a un único directorio de destino. Esto permite al usuario ejecutar un comando en lugar de varios: multiple values cp source1 source2 destination
 Hay algunas advertencias - típicamente, Su código (no el analizador de argumentos) debe manejar validación y lógica adicionales. only one argument Opciones permite a los usuarios especificar parámetros por nombre, a menudo en el formulario . If the user doesn’t provide an option, the tool uses its default value. Options --option value Por ejemplo: --log-level debug
 Un tipo especial de opción es una bandera — no toma un valor. La mera presencia de la bandera desplaza un comportamiento, como permitir una salida verbosa: --verbose
 Los nombres de opciones deben ser , para que los usuarios puedan entender fácilmente su propósito. clear and descriptive Ejemplo de implementación: @click.command()
@click.option('--verbose', is_flag=True)
@click.option('--log-level', default="info")
@click.argument('srcs', nargs=-1)
@click.argument('dst')
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 Ahora, la herramienta se puede llamar de varias maneras: cp --verbose --log-level trace source1 source2 destination
cp source destination
 Opciones cortas Hasta ahora, hemos utilizado nombres de opciones largas. Estos son ideales para scripts, ya que son autoexplicativos y fáciles de entender a simple vista. Sin embargo, para comandos rápidos y de una sola vez, los usuarios a menudo prefieren como En lugar de Sea selectivo al introducir formularios cortos.No todas las opciones necesitan una.Si su herramienta tiene muchas opciones, se acabará rápidamente con las letras intuitivas, especialmente porque varias opciones pueden comenzar con la misma. . short options -v --verbose frequently used options El ejemplo: @click.command()
@click.option('-v', '--verbose', is_flag=True)
@click.option('--log-level', default="info")
@click.argument('srcs', nargs=-1)
@click.argument('dst')
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 Ambas formas funcionan: cp -v source destination
cp --verbose source destination
 Validar la entrada del usuario y fallar rápidamente Una herramienta robusta debería y fallar con un mensaje claro y actuable.La mayoría de los marcos CLI admiten este patrón. validate user input early Por ejemplo, Click puede aplicar los niveles de registro válidos y los argumentos de camino automáticamente: @click.command()
@click.option('-v', '--verbose', is_flag=True)
@click.option('--log-level', default="info", type=click.Choice(["debug", "info", "error"]))
@click.argument('srcs', nargs=-1, type=click.Path())
@click.argument('dst', type=click.Path())
def copy(verbose: bool, log_level: str, srcs: tuple[str, ...], dst: str):
   ...
 Sin embargo, aún puede necesitar En nuestro El ejemplo: custom logic copy 
 
 
 Si hay una fuente, el destino puede ser un archivo o un directorio. Si hay múltiples fuentes, el destino debe ser un directorio, de lo contrario los archivos podrían sobreescribirse de forma inesperada. Las bibliotecas CLI genéricas no manejan estos casos automáticamente, por lo que esta validación debe estar presente en su código. Mensaje de ayuda Una buena herramienta siempre proporciona una buena . help message Los usuarios deben ser capaces de ejecutar algo como para ver: --help 
 
 
 
 Qué parámetros están disponibles Su significado Tipos o valores aceptados (por ejemplo, niveles de registro válidos) Un mensaje de ayuda claro ahorra tiempo, reduce errores y mejora la confianza del usuario en su herramienta. Siga sus patrones de ecosistema Finalmente, las grandes herramientas CLI se sienten Estudiar otras herramientas en su entorno y seguir sus convenciones, especialmente para . native naming options and arguments Por ejemplo, en el mundo de Unix, herramientas como , de , y Todos los usos y Como argumentos de posición, con Siempre antecedentes . cp mv rsync source destination source destination Nombres coherentes y letras de opción conocidas ( por el verbo, por el recurrente, por la sequía, para ayuda) haga que su herramienta se combine sin problemas en el flujo de trabajo del usuario. -v -r -n -h/--help Cuando su herramienta se siente como una parte natural del ecosistema, los usuarios serán mucho más propensos a adoptarla y disfrutar de usarla. Otros aspectos Más allá de los parámetros y argumentos, hay varios otros factores que distinguen a Estos aspectos afectan la forma en que su herramienta se integra con scripts, cómo los usuarios borran los problemas y qué tan fácilmente se ajusta a los flujos de trabajo más grandes. bueno Los códigos de salida Cada programa devuelve un Este código permite al llamador saber si el programa logró éxito o fracasó. exit code Por convención : 
 
 
 0 significa éxito Cualquier valor no cero indica un error Aunque no existe un estándar universal para los códigos de salida, es buena práctica que al menos . exit with a non-zero code on any error Para mayor coherencia, considere seguir las convenciones de la Estos son ampliamente reconocidos en el mundo de Unix. Guía avanzada de Bash-Scripting También deberías Incluirlos en la Cuando los usuarios o los sistemas de automatización entienden lo que significa el código de salida 3, pueden manejar los errores de manera más inteligente (por ejemplo, retry, skip, o alerta). document your exit codes --help Título: STDOUT vs STDERR Una herramienta CLI bien comportada distingue entre sus dos flujos de salida estándar: 
 
 
 STDOUT – para la salida regular y esperada STDERR – para errores, advertencias o mensajes de diagnóstico Esta separación permite a los usuarios y scripts manejar cada flujo de forma independiente. Por ejemplo, un usuario puede redirigir la salida normal a un archivo mientras mantiene los mensajes de error visibles en la consola: mytool > output.txt
 Suprimir los errores: mytool 2>/dev/null
 Si su herramienta escribe tanto datos como errores a STDOUT, los usuarios tendrán que filtrar la salida manualmente, y eso es frágil. Especialmente si la salida de su herramienta es consumida por otros programas, mantener STDOUT limpio y predecible es esencial. Formato de salida Si su herramienta produce datos que podrían ser consumidos por otras herramientas o scripts, es aconsejable apoyar formatos como JSON o YAML. machine-readable output Por ejemplo: mytool --output json
 Esto hace que la automatización sea mucho más fácil: otras herramientas pueden usar analizadores estándar en lugar de depender del análisis de cuerdas frágiles que se rompe cada vez que cambia el espaciamiento, el alineamiento o la puntuación. Sin embargo, no sacrifique la legibilidad humana. Muchos usuarios todavía ejecutarán su herramienta de forma interactiva. 
 
 
 Por defecto a salida legible por el ser humano (texto en formato nulo) Ofrecer una bandera (por ejemplo, --json o --format si desea soportar varios formatos) para la salida estructurada Algunas herramientas CLI también proporcionan , el envío de texto bastante impreso cuando se escribe a un terminal pero JSON cuando se conduce a otro proceso - similar a cómo o y comportarse. auto-detection kubectl gh Mensajes de error Un buen mensaje de error debe ser: 
 
 
 
 Claro - Declara lo que ha ido mal Accionable - sugiere cómo arreglarlo Consistente: utiliza el mismo tono y estructura a lo largo del Un mal ejemplo: Error: failed
 Un ejemplo mejor: Error: Could not open file '/tmp/input.txt' — file not found.
Hint: Verify that the path is correct and you have read permissions.
 El buen manejo de errores ahorra tiempo a los usuarios y les ayuda a construir confianza en su herramienta. Logging y Verbosity Los usuarios aprecian el control sobre la cantidad de información que ven. Un enfoque típico: 
 
 
 
 Silencioso para un rendimiento mínimo Verbozo para mensajes detallados Debug para el rastreo a nivel de desarrollador Diseña sus niveles de registro para que los usuarios puedan elegir la cantidad correcta de información para su contexto. Cuando se combinan con los códigos de salida adecuados, estos niveles hacen que el desgaste y la automatización sean mucho más suaves. Respuesta y rendimiento Si su CLI realiza operaciones pesadas, considere proporcionar o Por ejemplo: progress indicators spinners Downloading files... 45% complete
 Al mismo tiempo, evite las animaciones innecesarias o la salida cuando la herramienta se ejecuta en modo no interactivo (por ejemplo, como parte de un script). Conclusión Construir una herramienta CLI es relativamente fácil. Una buena herramienta de línea de comandos se siente natural, se comporta de forma previsible y desaparece silenciosamente en el flujo de trabajo del usuario. - se adapta a la forma en que los usuarios ya trabajan. good it A lo largo de este artículo, hemos examinado lo que contribuye a esa experiencia: 
 
 
 
 
 
 
 Parámetros claros y consistentes que equilibran simplicidad y flexibilidad Códigos de salida significativos que comunican éxito o fracaso Uso correcto de STDOUT y STDERR para separar los datos de los diagnósticos Formatos de salida legibles y estructurados para humanos y máquinas Mensajes de error útiles y comportamiento previsible Adherencia a las convenciones de su ecosistema, para que su herramienta se sienta familiar desde el primer momento En última instancia, las mejores herramientas CLI comparten una característica común: Comienzan rápidamente, fallan rápidamente, se explican claramente y se integran sin problemas en sistemas y scripts más grandes. respect the user’s time Si mantiene estos principios en mente - claridad, coherencia y empatía para sus usuarios - su herramienta CLI no solo Será un placer usarlo. Trabajo

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Read My Stories

Este audio es producido en el idioma original de la historia!

Cómo diseñar una herramienta CLI que los desarrolladores realmente aman usar

About Author

COMENTARIOS

ETIQUETAS

ESTE ARTÍCULO FUE PRESENTADO EN

Related Stories

Crecimiento de las criptomonedas: creación de perfiles de usuarios eficaces

¿Quieres ganar un concurso de redacción de HackerNoon? Esto es lo que recomiendan los ganadores del concurso #crypto-api

Creación de productos criptográficos centrados en el usuario: la importancia de los comentarios de los clientes

Toque para ganar: Telegram puede incorporar a los próximos 10 mil millones de usuarios de criptomonedas antes de Solana

Crecimiento de las criptomonedas: creación de perfiles de usuarios eficaces

¿Quieres ganar un concurso de redacción de HackerNoon? Esto es lo que recomiendan los ganadores del concurso #crypto-api

Creación de productos criptográficos centrados en el usuario: la importancia de los comentarios de los clientes

Toque para ganar: Telegram puede incorporar a los próximos 10 mil millones de usuarios de criptomonedas antes de Solana

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps