What makes code great? - A subjective list and some connected graphs
Tags: javascript, programming
Published: 2024-02-15 22:42:48

## Make a project for whom are unfamiliar with your codebase
If you were given the task to create a project, which is _primarily_ used by people who are _temporarily_ on the project, how would you design it?

> Think a little bit about before you read on!

Would you rather write a giant documentation explaining the "rocky parts" or would you rather create self explaining code? How would you make sure that people follow your best practices? How would you avoid needing to decline pull requests by letting people go on the wrong path? 

> Imagine yourself as a developer in a giant corporation who are given the task to add a feature to a repository they didn't even know about yesterday. From this viewpoint, you would be able to formulate your requirements.

Ready?

_Here are my thoughts then!_

## The (very impartial and personal) list to Great Code

- the code should be obvious as much as it can be (aka **Clean Code**)
- the project should be very easy to start, 1 or 2 terminal commands only required, no **Magic Scroll of Swift Running** needed to be put in `.bashrc`
- there should be very nice snippets, templates available for other people that they can then copy-paste, or use as a standard
- code has **clear expectations** on its `input` and its `output`
- the **data structure** for each function should be `obvious` (I'm looking at you, Totally Dynamic Language With No Types)
- **every element is searchable**, any external dependency is clearly defined in a place that is making sense (you know what is not searchable? `'my-' + filenamepart1 + '-' + filenamepart2 + '.js'`)
- with the code being a `connected graph` every component can be reached in a `logarithmic search` kind of way, meaning you click on the highest level element, you see a list of meaningful choices, you can select the next level and the next until you arrive at the code you need to modify (see asterisk below)
- there are no folders with `hundreds of files` in them, **everything is grouped** neatly, there is also a clear thought on how to expand (I'm looking at you `controllers` and `services` and `util` folder with no attempt at grouping.)
- there is **no witchcraft and magic recipes**: "Only name your first born file `index.js` in a folder that has the suffix `*-controller`. In there, you must leave bread and wine for the Gods of Convention and you have to chant _"Flaky test, flaky test! Fail me not, or else let the Devil ignore you!"_ three times, not more, not less! ... And don't forget to restart the Docker image running in the background."

### *: Connected graph...? Logarithmically searchable code? Sorry, what...?
By `connected graph` I mean the ability to traverse the code in your `IDE` with Control/Command+Click (or whatever shortcut you use for `Go to definition`)

If you click on something and your IDE cannot resolve it, then your code is not a `connected graph` anymore.

### "Utter garbage!" or "You missed..."
What's your opinion? How was the best repository you have had to work on? How was your experience working with codebase in a language you were barely familiar with?