What does code readability mean? • Hacker News Board

Re: What does code readability mean?

#41

Post by JoeAltmaier » Mon, Jan 08, 2018, 3:28 PM UTC

tekstar wrote: post #16

I once had a developer who consistently wrote unreadable code while trying to be clever. To give him useful feedback I needed to come up with a black and white heuristic for knowing if code is readable or not. The heuristic is this: Readable code can be explained in English sentences in one pass. Your code tells a story. When you read it do you introduce the characters in the right order? Halfway through a complex pa…

Fits with my thought: code should be systematic. A collection of unrelated bits put together as by a committee is hard to read.

Re: What does code readability mean?

#42

Post by virgilp » Mon, Jan 08, 2018, 3:29 PM UTC

kstrauser wrote: post #36

virgilp wrote: post #34

Earlier quoted context omitted.

That is a strange and "unnatural" (for me) use of the word "complicated". Cynefin[1] defines 'complicated' as "known unknows" and 'complex' as 'unknown unknowns'. The idea is that complicated things are non-obvious, but they are understandable (with expertise, you get the relationship between cause and effect). With complex, full cause & effect cannot be known apriori, it's just observable after the fact. That somewh…

I see it the opposite way. Some things are inherently complex, like heart surgery or launching a rocket. There are many things that have to work together perfectly or the whole thing goes south. Complicated to me means that complications have been added where they weren’t needed. A Rube Goldberg machine solves a simple problem that has been complicated.

Hmmm... I looked up word origins. "com" + "plicare" - "to fold together". You seem to be right, it's closer to the original meaning to use them like you say ("complex" = inherent complexity; "complicated" = "incidental/ added complexity"). I can't reconcile it with Cynefin, but I'll have to update my usage of those terms in a coding context.

Re: What does code readability mean?

#43

Post by danschumann » Mon, Jan 08, 2018, 3:32 PM UTC

Some good points. I think code-readability should be measured by people who are as accustomed as possible to the code base. IE, if you wrote all the code, how quickly can you refresh your memory ( 6 months later ), as well as trace down bugs.

Re: What does code readability mean?

#44

Post by stinos » Mon, Jan 08, 2018, 3:33 PM UTC

The author is spot on for 'standard' code styles. However when you enter the realm of crazy code styles (say, all code of the program in one single line, obfuscated code not meant for humans to read and so on), wouldn't we all agree that is in fact, objectively, unreadable? Beacuse actually reading it is simply too hard no matter how skilled and knowledgable you are? (note none of the OP's points cover this, except for 'The code offends my sense of aesthetics' maybe, but by a stretch).

And extending this somewhat further, I have already seen code written by humans which I am confident the vast majority of programmers would consider unreadable. Unfortunately including the guy who wrote it.. We're talking mixing indent witdhs/seemingly mixing all known code styles/complete lack of consistency/lines of hundreds of characters/big chunks of >20 newlines/... I think there is a point where this becomes unredable and it's not the reader who is to be 'blamed'.

Re: What does code readability mean?

#45

Post by crdoconnor » Mon, Jan 08, 2018, 3:34 PM UTC

Over time the first thing I've come to desire more than 'intrinsic' readability when joining a new project is a decent, up to date, hyperlinked glossary with all of the relevant acronyms and terms that will be used in the code. I've had variations on this conversation many times before:

* New coworker (me): What's an XYZ? (some core thing in the system)

* Coworker 1: An XYZ is [blah blah blah].

* Coworker 2: Actually, an XYZ may not be [blah blah] it could be [blah].

* Coworker 1: No! That's not right!

* Me: ugh...

Re: What does code readability mean?

#46

Post by hashkb » Mon, Jan 08, 2018, 3:35 PM UTC

stinos wrote: post #44

The author is spot on for 'standard' code styles. However when you enter the realm of crazy code styles (say, all code of the program in one single line, obfuscated code not meant for humans to read and so on), wouldn't we all agree that is in fact, objectively, unreadable? Beacuse actually reading it is simply too hard no matter how skilled and knowledgable you are? (note none of the OP's points cover this, except f…

He doesn't need to say "btw there's still some actually really terrible code out there" for us to know he knows it's true. He's making a point that wouldn't benefit from going there.

Re: What does code readability mean?

#47

Post by dahart » Mon, Jan 08, 2018, 3:36 PM UTC

virgilp wrote: post #34

artimaeis wrote: post #27

Earlier quoted context omitted.

Python's PEP 20 utilizes this view on simple v complex, and also covers the idea of complicated. > Simple is better than complex. Complex is better than complicated. I've stuck by those two lines of PEP 20 since I learned about them. The object is to write simple code, but it's okay to write complex code if your goal is to avoid complicated (unreadable) code.

That is a strange and "unnatural" (for me) use of the word "complicated". Cynefin[1] defines 'complicated' as "known unknows" and 'complex' as 'unknown unknowns'. The idea is that complicated things are non-obvious, but they are understandable (with expertise, you get the relationship between cause and effect). With complex, full cause & effect cannot be known apriori, it's just observable after the fact. That somewh…

I'd say don't try to use Cynefin's definition to understand what the PEP authors means. (Un)known unknowns is a pretty terrible definition of those words, it doesn't really match the common definitions at all.

Complex and complicated are, according to the dictionary, basically synonymous, and they mean something intricate or tricky that is composed of many interconnected parts.

I think the PEP authors were trying to say it's better for a piece of code to be clever and tricky to avoid complicated interactions with other code, if that's your only choice. I think they're trying to suggest complexity at a small scale is better than complexity at a large scale. But I'm just guessing, and I do think it could be better stated with two words that aren't synonymous.

Re: What does code readability mean?

#48

Post by seanmcdirmid » Mon, Jan 08, 2018, 3:37 PM UTC

mannykannot wrote: post #40

seanmcdirmid wrote: post #22

Earlier quoted context omitted.

Yes. But those words don’t come for free, they could be much more expensive than writing the code itself, it’s like trying to teach something rather than just doing it.

This is not the right model for assessing the cost of documentation. If the program is in any sense designed (as opposed to being assembled and modified on the basis of hunches until it appears to work), then the ideas expressed by those words must have been known no later than the completion of the work. Therefore, the cost of documentation is that of writing down these ideas, and the cost of not documenting is the…

You mean waterfall right? Ya, then I guess. If the program is understood before it is written (waterfall), then you merely write down these ideas along side the code. If programming plays any matter into evolving the design (as you say, “hunches” that go into a feedback loop), then this will break down quickly.

Edit. Never mind you mean afterwards. But is the assumption that design can occur independently of programming really true in practice?

It depends on the complexity of the problem you are working on. Something well understood before programming starts has a better chance of being well documented with short prose (because it is well understood, a lot of shared universal context can be relied on). There are lots of things out there that don’t meet this criteria, however.

Re: What does code readability mean?

#49

Post by kstrauser » Mon, Jan 08, 2018, 3:39 PM UTC

virgilp wrote: post #42

kstrauser wrote: post #36

Earlier quoted context omitted.

I see it the opposite way. Some things are inherently complex, like heart surgery or launching a rocket. There are many things that have to work together perfectly or the whole thing goes south. Complicated to me means that complications have been added where they weren’t needed. A Rube Goldberg machine solves a simple problem that has been complicated.

Hmmm... I looked up word origins. "com" + "plicare" - "to fold together". You seem to be right, it's closer to the original meaning to use them like you say ("complex" = inherent complexity; "complicated" = "incidental/ added complexity"). I can't reconcile it with Cynefin, but I'll have to update my usage of those terms in a coding context.

I've had this conversation with few people - mainly peers with whom I'm discussing our craft. Most recently it was with a junior engineer, and I wanted to pin these definitions down precisely so that we had a common vocabulary for describing ideas we were developing. I mention this because I haven't heard these terms commonly used in any particular context so I don't think there's an agreed upon "correct" definition of them. I think my definitions more closely jibe with the normal English meanings, though.

Re: What does code readability mean?

#50

Post by bradfa » Mon, Jan 08, 2018, 3:39 PM UTC

The biggest helper for me when trying to read other peoples' code is having a document (or documents) which describe what the heck the code is supposed to be doing in human terms. This is especially true when I'm not super familiar with the business history, long forgotten bug fixes, and nuance which was previously worked around or implemented.

Software documentation almost always sucks, in my experience. When I do find well written documentation that reflects the code, it becomes much easier to understand the code quickly so that I can make the changes I want to make.

But nobody likes writing documentation.