add "Coding with empathy"

[sndrs]

Adds a section on preferring empathic approaches to how we write our code.

This tries to capture recommendations based on a number of recent discussions we've had in/around the CSTI team, but it is not intended to only apply to client-side code.

please add your thoughts!

co-authored with @jamie-lynch

[JamieB-gu]

This is interesting 🤔. It may be important to define what we mean by "idiomatic" as part of this recommendation, as I think some of the discussions in the PR you referenced exposed the fact it means different things to different people.

I suspect this issue is more acute in JavaScript than in other languages. It's not like, for example, Python which has PEP 20 and a massive standard library to draw on for examples. The language is typically very permissive, it tends to be written in different styles depending on the organisation or codebase, and there's no real standard library to draw on for reference. It might be preferable to figure out a "Guardian style" for writing JavaScript (or TypeScript?) and orient the recommendation towards that?

I'd also point out that idiomatic TypeScript may look quite different to idiomatic JavaScript. Programming with types allows you to solve problems in very different ways, and the patterns you follow to structure your code are likely to reflect that.

[sndrs]

It might be preferable to figure out a "Guardian style" for writing JavaScript (or TypeScript?) and orient the recommendation towards that?

that could be something we want to do for typescript (or for any specific language), but these recommendations are intended to be more generic

[davidfurey]

To me the title of this new section is misleading. It seems they are actually recommendations on programming style, with idiomatic programming being one aspect of this.

The PR reminded me of Felienne Hermans' talk "How to read complex code" (https://www.youtube.com/watch?v=GUtfW7SHMc4).

[sndrs]

@davidfurey that's a good point. i guess we started thinking that would be the subject and on writing it felt like we were actually getting at something different – more about why than which specific things the guardian wants to encourage.

how do you feel about something like Coding with empathy?

[davidfurey]

I think "Coding with empathy" is a better summary of what these recommendations are about than "Idiomatic programming".

[sndrs]

is this better thought of as "Writing useful code" or "Programming for productivity" or something?

[mchv]

Looks good to me 👍
Could we ask some of our new starters if they understand what we means?

[SiAdcock]

Love this 👍

[markjamesbutler]

lgtm - thank you for taking time to reach this conclusion.

[akash1810]

Wonderful stuff! This revision history is pretty noisy, I recommend squashing commits.

This is a fantastic video that eloquently explains why keeping a clean revision history is favourable. (Maybe we should add some revision history recommendations too?)

[sndrs]

@akash1810 that talk is excellent. i'm 100% guilty of nonsense commits and it's pretty much changed my mind completely! should we add it here do you think?