From d468f22f6f474fc233dbf9c4ed533ee4c992a3ff Mon Sep 17 00:00:00 2001 From: Brad Treloar Date: Sat, 8 Mar 2025 00:38:49 +1030 Subject: [PATCH] WIP Coding for humans --- docs/programming/general/coding-for-humans.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 docs/programming/general/coding-for-humans.md diff --git a/docs/programming/general/coding-for-humans.md b/docs/programming/general/coding-for-humans.md new file mode 100644 index 0000000..0c08740 --- /dev/null +++ b/docs/programming/general/coding-for-humans.md @@ -0,0 +1,37 @@ +# Coding for humans + +- Code is instructions for machines. + +BUT + +- Code is read by humans. +- Humans need to be able to understand code easily. +- Not all humans think about code the same way + +SO + +- Write maintainable code + - If design is about usability, coding is about maintainability +- Write boring code that's easily modified and extended + - Consistent patterns + - Avoid obscure and fancy syntax + - Aim for maximum readability +- Use dev tools to make the job easier and less error-prone + - Syntax highlighting + - Code completion + - Linters and formatters + - Static analysis + - Statically typed languages or type hinting +- Write documentation to guide devs + - Explain how programs work so devs don't have to reverse-engineer your + team's work. + - Explain the reasoning behind obscure solutions. + - Document pitfalls you've fallen into so other devs don't do the same. +- Write code that accommodates different kinds of devs. Devs can be: + - Inexperienced: + - New to the codebase + - Opinionated + - Impatient + - Bored + - Tired + - Pressured