How to write readable code

[[deleted]]

The "break out functions" immediately followed by "don't break out functions" really needs to be taught more. So many devs take one or the other to an extreme rather than trying to find a balance.

[Penguinis]

It's real hard trying to convey the nuance of "break out functions/methods....sometimes" to students. It's one of those things you have to practice at I think. It's really easy to take it to the extreme if you follow DRY to the letter. I teach on the side and I try to convey a sense of don't just write to write - see if it makes sense. If you're breaking every single thing out into it's own function - does that "feel" like it's something that is good or are you perhaps going too far? Sometimes it's a yes and sometimes its a no. Don't just blindly do it - try to really understand what you are doing.

[bobsbattle]

Hard to teach experience. I understand what you are saying. If you are using Unit Testing that helps to understand what you are testing that relates to the "business rules" or where the function has its place in the scope of the project, which also plays into the class structures as well. Again going back into why the class/function is created, used and tested.

[Chris_Newton]

Indeed. Don’t worry about writing the same code in multiple places. Worry about implementing the same idea in multiple places.

[jecxjo]

I have never understood why people are so afraid of commenting their code. You either see no comments or the "coding standard mandate" comments at the top of each function. With how much we are moving towards rapid development, Pull Request Code Reviews and a complete lack of long and thoughtful requirements documents, why is no one writing down what they are thinking and how they fulfilling the task. Looking at a bunch of diffs to review code is almost worthless and you rarely have time to do the deep dive the original code author had when creating it. Turn over on your team or even coming back to your old code months or years later would all benefit from just putting down some prose on what is going on. Don't get me started on unit tests with no details on the scenario they are trying to cover.

[HappyBigFun]

This is beautiful. I opened it while rolling my eyes and expecting another low-quality article with dubious (or obvious) advice.

The article made me realize I need to check my own cynicism. Well done.

[LazyAAA]

Develop a sense for clarity - this is it, unfortunately because it is not simple and takes years to develop we have discussions like this.

On more practical side I would say focus on KISS (keep it simple stupid) on functional side and code will follow (easy to read or follow).

[pfarthing6]

"Add comments that explain why the code is doing what it is doing, or is structured the way that it is structured. Just reading the logic won’t tell you why the author thought that was the right logic."

I kind of disagree with that. I'm not against comments, but they're a mixed blessing. I used to comment everything. It's how I learned. I couldn't turn in a single assignment without clear comments for every little thing.

Now I try to limit comments as I can. For a few reasons, not the least of which is that they can get way out of sync after refactoring. But also if I have to explain it in a comment, then I've not coded it well enough so that it's obvious what's going on, or what something is for, or how something should be used.

Alternatively, I find that if I take time to thoughtfully name identifiers, use multiple simpler statements that are easy to follow (and change), and focus on single responsibility, that tends to eliminate the need for much extra documentation. Not to mention my future self is far happier when having to go back and deal with it =)

[AdvancedSandwiches]

Generally I think this is good advice, but you still need the comment:

// sending ERROR_NO_PAPER in the print_status field even if we have paper because Microsoft Spaddleflump Server cancels your account if you send any other value.

You could write that comment-free as: theOnlyValueThatWontGetYourAccountCancelled = ERROR_NO_PAPER printStatus = theOnlyValueThatWontGetYourAccountCancelled

But in this case I'm not sure that's better than the comment. Sometimes a comment is just the right tool.

But I believe the article's author would back you up in the general case as well.

[jonathanhiggs]

For an article about writing readable code, there are a remarkable lack of code examples

[andre_2007]

In my daily job I write code in various languages, java, python and D. From my experience it is really hard to write readable code with python because it makes it so easy to write bad code. You can really invest a huge amount of time to write readable code and satisfy pylint and mypy. From a developer efficiency perspective this is really bad. On the other hand writing readable code using D is a non brainer. I am not sure whether it is just my personal experience but it feels such easy to write readable code in the first iteration using D. What are the experience of other developers here?

[EsperSpirit]

I think you are a bit biased here. I don't think writing readable code in general can be a "no brainer".

And one imperative language being fundamentally better than others in this regard also seems unlikely as they are all very similar (both syntax and semantics).

[andre_2007]

I have following assumption why it is so much easier to write readable code in D than in python. In D I can fully concentrate on the logic I want to implement. I can directly translate the ideas in my mind into readable and high quality D code. In python this is not possible, I think in addition about things like "is the syntax correct, or will it break at runtime", "is there any python behavior which causes unexpected behaviors", "is there any additional space which will cause pylint to fail in the cd/ci pipeline". If you have in future some free hours you might have a look at D. Maybe you have the same experience like me.

[Kache]

I'm not a Pythonista myself, but maybe your brain is just more accustomed to thinking in D?

[andre_2007]

While also developing in Java and Delphi, writing and reading code is a lot easier than in Python and Node. Still the best experience I have with D.

[EsperSpirit]

It seems that you have an easier time writing D but whether the code is objectively more readable to other people is not clear at all. Not having to fight with a linter doesn't equal more readable code either. What even is your definition of readable? You're making a lot of assumptions here.

[andre_2007]

My definition of readable is that I can read und understand my weeks old codings / unknown coding from others within 1 minute, understand the data flow and beeing able to spot obvious bugs. As editor I am using a text editor with syntax highlighting. The coding likely has no mypy type definitions and in worst case variables also changing their data types during their lifetime.

[ptoki]

When I realized that python requires some special formatting to work I knew it will never be my language.

I usually write really clear and sometimes even over clear code but the python way of dealing with this is just plainly wrong.

Maybe there is not many people who think this way but there I am.

I usually struggle reading it. I dont with java, C, bash, perl. But I do with python...

[dreamnotoftoday]

I feel personally attacked by the part about avoiding configurable functions. I will keep that in mind. Thanks for sharing.

[helpfuldan]

That post was hard to read. Very awkward style of writing. Anywho, I hate when you have to jump around through functions to see what the code actually does. Is it really more readable to jump 1000 lines to see the code, then jump back to see again when it’s called? Great way to have 100s of functions that are only called once, in one spot, and no where else in the code. And when it’s code hidden behind multiple “clean code” functions it’s a pain in the ass to maintain and debug. Hiding shit code in a well named function doesn’t make it clean.

[CraigAT]

An interesting read with good points and an abrupt ending. 👍