Item — HN Reader

The challenge is, how do you teach it?

Like many writers, many coders think their code is readable and are resistant to feedback. They literally do not see the problem.

You can institute all the rules and guidelines you want, but they see it as friction and overhead and only do it because they are forced to.

4 comments

Plain real world experience. So one way is:

1. Learn all the guidelines/rules/principles out there (or at least the ones that appear to be the most important or popular ones)

2. Apply them in real projects (and keep working on such projects for at least N years)

3. Realize how painful is to maintain some of your solutions. Unlearn what you have learnt

Point 1 is important (otherwise you may miss other people's good solutions). Point 3 is important (self-critic, self-introspection, let your ego go away)... but for me the most important one is point 2: unfortunately most fellow engineers out there jump from job to job after 1 or 2 years and they don't end up maintaining their own code (so, they usually don't get to experience point 3).

Where N is at least 3, in my limited experience.

The first step is to agree on what it is.

I've never actually seen rules or guidelines that were:

* Non-trivial - e.g. not about spaces or line lengths or something.

* Objective and specific - e.g. with a vague principle like "single responsibility" it doesn't take much to trigger an argument about what constitutes a responsibility.

* Actually made it more maintainable - I remember some of the DDD guidelines were non-trivial, objective and specific but they 3-5xed the SLOC.

I tried writing some of my own, but it's a lot of work, doesn't generalize very easily and is as likely to spark an argument as it is to actually help.

But those are "writing techniques" and not the actual writing / stories. As long as you're having a "conversation" with a codebase by continually reading and editing code you know what parts of the code flow well and are expressive and what parts are not. I think a discussion about the eloquence of a codebase should be had in continuity, parallel to all other individual tasks.

Actually the article illustrates some of the criteria like if the code answers "how/what/why" questions. From my own experience the codebases where the code didn't answer those questions were the worst.

A big issue seems to be that what is "readable" to one person isn't necessarily "readable" to someone else, and you end up with endless yakyak over whether the braces should be inline with the `if` statement or not.

My take is that some compromise is key: Yes, there are some standards that objectively make code easier to understand. But you should also learn to read code that isn't written exactly as you'd like it to be. And try to stay consistent with the overall style.

The yakyak is all but a solved problem in many languages.in c++ Clang format on submission, and clang format on updating files to your preferred local syntax.

No kidding. The number of projects and developers that I see that refuse to use the tools is quite interesting. One project I worked on dozens of engs say 'your code is so easy to read'. Then one dude comes along and it 'gives him a headache'. He also spent way too much time refactoring and renaming things. He became obsessed by it. Every few weeks changing the spacing, indentation, and naming conventions. Then expecting everyone to keep up with whatever decision he made at 10PM on some random Friday 3 weeks ago in a fit of open every file and change everything. He looked like the hardest working person in the group but he was adding zero new features. It killed the project. The worst are the groups that say 'everyone is a professional we do not have to deal with that'. You then end up with dozens of modules with whatever rando style they happen to like that day. Pick one. Put it in the tool. Stick to it for a decent amount of time. If it is not working bring it up in a meeting.

The ‘black’ formatting tool for python has worked amazingly for my projects. It may be controversial, but I think Python’s strong opinions on code format and conventions was one of the things it got right.

It might be solved for the very basic stuff (spacing, indentation, etc), but there's still plenty of yakyak to be had for higher-order "religious" debates...

That's who you need to let go. People resistant to feedback are bad for any role in any company, and if they have their heads so far up their... that they think they know how the code looks for someone else better than that someone else, they really shouldn't have been hired in the first place.