> > When writing code you have the motto "don't make me think" in mind

> I disagree with this phrasing. We’re engineering after all. The entire job is thinking.

Well, sure. The implied full phrase - more technically-correct, but less pithily-quotable - would be something like "don't make me think unnecessarily; let me spend my thoughts productively. If you've already spent brainpower on figuring something out, explain it to me directly and clearly rather than forcing me to go through the same discovery process"

So - yes, if someone doesn't want to think _at all_, they shouldn't be a programmer; but if someone has an aversion to being forced to solve a problem that someone else has already solved, they likely have the right "shoulders-of-giants" mindset.

(For any potential pedants - yes, there are some practices you simply have to work through before understanding dawns, which cannot be explained directly. Still, though - the explanation should aim to minimize unnecessary thought-requirements so the student can get straight to learning)

Just because fires are inevitable in the business of firefighting, doesn’t mean that firefighters are in the business of starting fires.

In engineering, thinking is inevitable but also costly and error-prone, and the more thinking an engineer needs to do the higher the costs, the higher the risks of errors. We should be striving to minimize the thinking required every step of the way, even if we’ll never get it down to zero; that’s the only way to keep it from spiraling towards infinity.

Teams are not a static concept, they change members over time and so talking to them has a net zero effect. The newer members will not understand this clever new concept that was introduced, worse, they will misunderstand it or work around it. Which brings us back to don't make me think. If the concepts can be kept as simple as possible, which overlaps greatly with readability, it will have achieved its purpose.

"I didn’t have time to write you a short letter, so I wrote you a long one." -- Mark Twain

It's difficult to explain how to write well, but bad writing and bad computing systems typically impose far greater cognitive burden on readers than might have been necessary. There is an art to software engineering.

Functional programming does involve idioms, though I would say no more than imperative programming, or OOP, or some other paradigm. One of the overarching themes of FP is to reduce the cognitive footprint to only the essential properties of the problem to be solved.

A novice artist can produce a recognizable figure using many pencil strokes. It takes a master to produce a compelling likeness with only the lines that are necessary.

Maybe a better phrasing is "don't make me think about inconsequential details". If I need to figure out your particular idiom of writing a for-loop, then that takes time away from thinking about what the code is actually doing. Even if that idiom is perfectly fine and works the same as any other for loop, it's not worth it if it makes people think about unnecessary things.

But like you say, if you've got an idiom that's actually useful (like programming in a functional style to avoid action-at-a-distance side effects), then document it so the whole team can get used to it and stop having to think about it.

When I write functional code I start with Peano and then go from there, ommiting comments are descriptive names. It encourages thinking in myself and my coworkers.

IMHO, comments are required for capturing "the why." Code captures how it works, when it is used, and what it does.

But only the author(s) can capture why it exists via commenting.

Same. And it’s helpful not just for other people but for me also when I’ve forgotten how it works and now there’s no one to ask.

I don't really believe this but ok. I worked at a functional / typescript heavy shop where when I had parsed what a complicated set of steps was doing discovered multiple redundant queries and a library that was parsing strings into code. But damn some of those functional paradigms chef kiss /s. Imo my dumbass code , besides being demonstrably more performance was way less of a liability.

> On the other hand, writing code that the most junior in your team can understand leads to mediocre code.

Disagree on a couple levels. First, while the overall architecture of the system might be complex, there shouldn't be any one single function that isn't readily readable by a junior new hire. Complexity is in the system, there should be no complexity in small sections of code.

Second, the ultimate level of mastery is to be able to build simplicity. Any newbie can write a convoluted mess that nobody can understand.

> On the other hand, writing code that the most junior in your team can understand leads to mediocre code.

Sorry but this is absolutely false in almost all regular corporate software jobs.

As i get greyer, I find myself spending much more time planning before I write any code now; what I would previously have run into headfirst and solved with a bunch of advanced language features and complicated logic usually now ends up being implemented in much less and simpler code.

This is the sign of a senior developer, in my book.

Writing code anyone finds hard to understand is a marker of inexperience to me.

I don't think anyone is confused by flatMap in isolation. It's chains of not-very-obvious data transformations. When I have to do one of these I typically break out each step into it's own line/block and add comments with an example object to show precisely what every intermediate step looks like. They're hard to follow otherwise.

And functional programming snorts these long chains like lines of coke and when you add some random curried functions and people who write in a pointless^H point-free style it's easier than folks like to admit it to end up with write-only code.

I've never found myself with a block of code that could be expressed as a flatMap and thought it would be easier to understand by expressing it as such. I'm perfectly capable of writing functional code but after reading it back I almost always throw it out for something imperative because it's clearer as to what's really going on. The code is going to be executed in an order at the end of the day, why make it harder to see what it will be?