Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What does code readability mean?

typicalprogrammer.com

Post reply on HN
Print view View original

71–80 of 134 posts

Re: What does code readability mean?

#71

Post by mannykannot »

seanmcdirmid wrote: post #66
mannykannot wrote: post #61

Earlier quoted context omitted.

My description of blind trial-and-error programming is not a veiled reference to agile development, if that is what you are thinking - it is, rather, an anti-pattern in development that is neither agile nor waterfall. There is nothing in agile that says you should just try things until something seems to work. No line of code gets written without the programmer of having an expectation of it making some contribution…

There are plenty of cases where programming helps you explore the design space, where you have little knowledge about the APIs you are using, so you poke them a bit here and there, obtaining experience in knowing how to use them in the way that you need (because, let’s be honest, even the best frameworks have defficiencies in their documentstion, if you decide to read the docs at all). Likewise, it isn’t that weird t…

Your example is a case where small amounts of additional documentation can be useful. If you are working with a poorly-documented API and you find something that is unintuitive and non-obvious (it might be as simple as an arbitrary choice between equally valid design options, where exactly one needed to be chosen) but which matters in what you are using it for, then a note of that fact could save a lot of time in the long run, depending on what you are coding for: if it is just for yourself, then you only have to consider what is best for you, but if it is an actual product where it is likely that others will have to understand it, that note might pay for itself many times over.

Re: What does code readability mean?

#72

Post by maxxxxx »

gregjor wrote: post #68
maxxxxx wrote: post #7

Earlier quoted context omitted.

Totally agree. It's a lot of work though and can be humbling to find out that the previous people weren't complete idiots. Reading code also doesn't really get rewarded. It's easier to declare the work of people who aren't there anymore as bad and rewrite everything.

Throughout most of my career reading and maintaining code got fobbed off on the new programmers and the less skilled. Maintenance programming has a bad reputation, partly because it requires reading and figuring out someone else's code. Now I make a living reading and maintaining code no one else will touch. Lots of companies can't afford to rewrite a mostly-working system, or they can't take the risk. I found a nich…

Neat. How do you find these gigs? I actually like working on old stuff and refactoring myself.

Re: What does code readability mean?

#73

Post by sp332 »

virgilp wrote: post #38
olau wrote: post #29

Earlier quoted context omitted.

> With that definition - it's absolutely correct to say that the code should be as simple as possible. Yet, it is humans who need to read it. This is the end goal. If you rewrite the code to satisfy a theoretical objective criteria of simplicity, but end up with something that people reading the code find harder to read, then you have failed. It's the same when you design a UI.

But if you don't have an objective criteria of simplicity, how can you even hope to have universal agreement of what is "simpler"? Humans are complicated beasts. Saying "people find the code harder to read" doesn't help me know what I should do. If I have no objective criteria, then it must be subjective, and then all that "simple" means is that "this is easiest for me right now " - which, from experience, I claim to…

There's a term for the objective measures of quality: kwalitee. It's kinda like quality, but quality is hard to define let alone measure, so kwalitee is good enough for some purposes. https://pypi.python.org/pypi/Cheesecake https://qa.perl.org/phalanx/kwalitee.html

Re: What does code readability mean?

#74

Post by gregjor »

maxxxxx wrote: post #72
gregjor wrote: post #68

Earlier quoted context omitted.

Throughout most of my career reading and maintaining code got fobbed off on the new programmers and the less skilled. Maintenance programming has a bad reputation, partly because it requires reading and figuring out someone else's code. Now I make a living reading and maintaining code no one else will touch. Lots of companies can't afford to rewrite a mostly-working system, or they can't take the risk. I found a nich…

Neat. How do you find these gigs? I actually like working on old stuff and refactoring myself.

More info in the other articles and About and Hire Me pages on my web site.

Re: What does code readability mean?

#75

Post by Verdex_3 »

olau wrote: post #29
virgilp wrote: post #15

> “Good code is simple” doesn’t actually say anything. [...] What we call “simple” depends on our experience, skills, interest, patience, and curiosity. I like Rich Hickey's stance on this: "simple" is objective (antonym: "complex"), whereas "easy" is subjective (antonym: "hard"). Easy depends on skills, interest, patience, curiosity - but simple does not. Simple is about lack of intertwining of concerns. About writi…

> With that definition - it's absolutely correct to say that the code should be as simple as possible. Yet, it is humans who need to read it. This is the end goal. If you rewrite the code to satisfy a theoretical objective criteria of simplicity, but end up with something that people reading the code find harder to read, then you have failed. It's the same when you design a UI.

What's the alternative though? Write your code such that people subjectively find it easy to read? Then you have to know the set of all people who are going to read your code AND how their internal (and possibly inconsistent) "easy" function works AND those people can never change personally AND no additional people can be added to that set unless they match someone else's "easy" function AND the sum of all the readers' "easy" functions have to result in at least some chunk of code being "easy".

At least with an objective criteria anyone who doesn't understand your code has something objective they can get better at in order to understand your code. And this is something that everyone can synchronize on from now and here to infinity and everywhere.

Re: What does code readability mean?

#78

Post by pythonaut_16 »

tboyd47 wrote: post #28
gregjor wrote: post #24

Earlier quoted context omitted.

I sometimes describe programming as a one-way hash operation on requirements. A lot of information and context gets lost when writing software, and I haven't seen a workable solution to that problem yet.

This is closer to the root of the problem than saying code is unreadable... the information isn't lost because of the code being produced, it's lost because the developer leaves. Documentation won't work because requirements change faster than they can be documented. I don't know a solution other than just trying to convince that developer not to leave.

IMO that's part of why readable code is so important. If I can look at a piece of code and understand its behavior then I can know something. I might not know what stated requirement it was trying to solve, but I can know for sure what requirements it implements.

Compare that to sloppy code bases with side effects everywhere where you don't know what it's supposed to do or what it does.

Re: What does code readability mean?

#79

Post by gabemart »

The author consistently compares code language style to literature language style, but I don't think it's a helpful comparison at all.

Literature operates by an intractably complex interaction between the words written on the page and the mind of the reader. Exchanging a single word for another may totally alter the effect of a passage, based on factors like the meaning of the word, the associations the word has for each reader, and the aesthetic appearance and sound of the word.

Moreover, we have no objective way of measuring the effect of literature. We don't have a test that can measure how much more empathetic I become after reading a novel, or how much more I understand the human experience.

Computer code typically has measurable outcomes. While "readability" may still be a relatively subjective measure, we can at least say "these two versions of this function are equivalent" if the outcome is the same - the array is sorted correctly, the transaction amount is calculated correctly, the graph is rendered with the same pixels.

This means that editing computer code is nothing at all like editing literature. The cliff-notes version of Macbeth can never produce the same effect in the mind of the reader as reading Macbeth -- but a function that is subjectively easier to read can be shown objectively to produce the same effect as the original function.

Re: What does code readability mean?

#80

Post by deckar01 »

Time is a commodity. The extra time spent reviewing or maintaining code that is difficult to read would be better spent writing the code well the first time.

In open source development, a maintainer’s time is often extremely limited. If you can’t make your code easily readable for that maintainer, then your contribution is worthless. You have created an asset with a transaction fee that prices you out of the market.

Post reply on HN