Write simple code that even a junior programmer can understand?

Question

The following advice is often said by developers:If your code is meant to be read by other developers, then no matter how experienced you are a programmer, your code should be so simple and clear that even a junior programmer can understand it.This belief or advice is often repeated in articles and in comments on forums like HN.But is this a belief that everyone agrees with? Or is it a belief few programmers practice in real life?What are the examples of medium-sized (or larger) open-source projects written in simple and clear code suitable for programmers of all levels to understand? Are there standard libraries that meet this criteria?In contrast, programmers often confess that [insert framework here] is full of 'magic'. I've even read complaints from developers that some SSGs (static site generators) are the opposite of simplicity of when reading the code. Does this suggest that 'magic' is actually the more common scenario among programmers?Could it be that the experienced programmer avoids writing code at a junior-level comprehension because of the gaze and (silent) judgment of their colleagues?Your thoughts?

jleyank · Accepted Answer

If the code is not intended to be thrown away after use, it should be written as simple and as cleanly as possible. You or somebody else will revisit the code in 6+ months to fix a bug or make an enhancement. This requires reestablishing state and simplifying this process makes it safer and quicker.
There are a few times where code has to be cryptic and magical, but usually developer time is more valuable than cpu time. Good, stable code makes for happy users which makes for paid (or fame++) developers.
Kernighan: “Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?”

groffee · Answer

Anecdotally I've found that the better you get, the simpler your code gets until it looks like a junior actually wrote it. But it takes skill to write something so simple.

drakonka · Answer

For me, this is more like a guideline to aim for, not a rule to die by. I aim to make my code as simple as reasonable while also striving not to compromise _too_ much on performance. If some feature just requires more complexity than a junior programmer would easily understand, I don't beat myself up over it and be sure to leave relevant comments where I feel they're necessary.Maybe this is very stuck-in-the-past of me, but one simplistic example for me is for loops. Various languages have different handy ways of iterating over a collection with `foreach`, `for in`, `for of`, LINQ methods, etc. Personally, I just think a simple `for (var i = 0; i < blah; i += 1) {}` is the simplest variation to read and understand without wondering about internals like which value you are iterating on and such, which usually translates well across languages in terms of readability. I don't think this is a "best practice" by any means, just a personal preference that I perceive as resulting in generally more readable code.

tmaly · Answer

I think code should be written to maximize readability.
But I also think there needs to be a maintained design doc that describes the abstractions at a high level and connects the design to the business terminology.
Having a 10,000 foot view not only helps junior developers, it helps new people joining the project.

thorin · Answer

I'd agree with this as someone that is now rarely writing production code, but often reading other people's code as part of designing components or analyzing issues. I've recently seen very complex ternary expressions, linq queries and historically sql which were essentially unsupportable. In future I would try and spot this earlier and expect comments, tests or just some refactoring to better describe the process. People working at a low level find it difficult to realise that their code is essentially unreadable, we've all been there and come back and had no idea what we were doing!