Navigating Code - crccheck/crccheck.github.io GitHub Wiki
I'm trying to develop an analogy to illustrate why people should write simpler code. I'm basing it off of transportation and based on me trying to get around NYC.
If you drop new code in front of someone, how quickly can they get to 
?
The less someone has to spend to understand your code, the faster they can start contributing.
How hard is it to get around your city? How far can you get knowing:
- We drive on the right hand side
- Red means stop, green means go
- ST run east/west, AVE run north/south
- The C train alternate schedule for the construction on March 25th
How about your code? How far can you get knowing:
- A basic level of coding
- An advanced familiarity with the language
- Knowledge of the patterns and tools used within the organization
- Knowledge of the patterns and tools used within the team
- You just made something only you understand
Do you even know what other people in your organization would find familiar?
How to make code easier to navigate
- Use standard build systems: npm scripts, Makefiles, etc.
- Low complexity
- Standard interfaces
- Code review
- Code review with outsiders
- Code like you have short-term memory loss
Signs your code is hard to navigate
- You have to learn something new to understand the code
- You have to touch many things to do one change
- You have to have multiple windows open to trace logic
- It's impossible to create a concise snippet
- Code analysis tools won't process your code (dynamic imports, anything that breaks jump to definition)
- Code no one knows what it does
- "Here be dragons" code
https://css-tricks.com/write-better-code-3-levels-code-consistency/ calls this "consistency"
The "Hello World" test
Does your code look like it was copy pasted from an example? If so, good. Example code typically:
- doesn't do a lot
- is readable
- well documented/self-documenting
- uses the simplest syntax possible
Would you be proud to put the code you wrote in the README for the project?