Justin Lee
Lots of work to make them easy for humans to navigate and use
People scan UI in predictable Z-shaped pattern
People often scan directly to the bottom name=="main" because functions must be defined first, and that's where they're used.
Ambiguous naming conventions versus clearn names at potential cost of verbosity
Short obscure or terse names (add, days, ok, fmt, check, etc., overloading function names) versus clear and potentially verbose but more informative names
Instead of one chunky block of code, provide spacing and group logically similar parts of the code. Use whitespace to separate distinct pieces of logic.
Noisy and flat versus expanding hierarchy
timing data embedded in a function versus using a decorator to apply timing taking the timing code away from the main purpose and logic
Lack of required field indicators. User should be focused on filling out the form rather than meta level figuring out how to fill out the form.
Placeholders for phone numbers, for example. Asterisk for required fields.
Ambiguous variable names (a, b, c...)
Additive changes lead to fewer regressions, but adds a lot of technical debt and bloat. In adding arguments, people usually add paramters and defaults to a function rather than redesigning a function with new logic.
Takeaway: treat function as a form
Form with fire icon buttons; button icon not intuitive. Improve with a trashcan icon to be more clear that the button is for deleting.
Nonidiomatic naming conventions versus predictable filenames corresponding to their purpose. Not prescriptive, may be particular to a development organization or even peronal projects.
Requires opening a file to confirm purpose.
Example: FastAPI codebase might be a good example for naming.
No explicit example
Code standardization
black, ruff, flake8,
pylance, mypy
Provide code quality feedback in a natural way
Feel empowered for yourself or others to contribute to your code.
Clean code, coupled with AI best practices can reduce token wastage.