Code skimmability as the root cause for bad code structure decisions

Topic: Code skimmability as the root cause for bad code structure decisions

5

I want to start by explaining what I mean by skimmability. Skimmable code tends to have consistent shapes and is relatively uniform across the codebase. This makes the code recognizable without reading the details and allows for a relatively fast read of the code. It seems that this is: 1. Desireable 2. Makes programmers think they understand the code even though they missed the details Apart from #2, it appears that writing for skimmability limits your options regarding code structure. Long functions or dense lines are not skimmable. Instead we see codebases with a million files that do "only one thing", lots of classes, single-line functions, getters/setters everywhere and heaps of syntactic sugar. My opening argument is that I don't think much of the code structure issues we usually see are a results of bad theoretical ideas about "good code", but instead result from the desire to write skimmable code. (or perhaps the bad theories are just constructed such that they result in skimmable code?) I don't think code needs to be skimmable at all and we should try to avoid skimming code even if it is skimmable in order to understand it properly.

So the first I'm curious to discuss is what makes the code skimmable. Which patterns do make the code skimmable, and how do they affect the code

It's about making code recognizable at a glance.

10:02

And building a sort of mental database of those shapes in a codebase, so the meaning of code shapes can be specific to a codebase.

10:02

By shapes I mean something like this:

10:02

But then, if you think there shouldnt be obligation about skimmability, what happens when you refactoring-rewriting some parts of the code

You might get an idea for what this does without reading it.

You may have to put more time than it needs to be

10:03

I think there should be mid point

yeah. if/while (something) do some object method calls or field access chain :D

Oh, I'm not suggesting that you need to achieve some sort of 100% compression to the code. Just that skimmability is not something you need to move towards. If it happens naturally then it's fine.

If you like, writing for new codebase, or its a completely new topic to you, you are going to rewrite it

and when it happens, you will want to understand the code, without wasting too much time on it

But I would say that if you're rewriting some code, you should probably read it carefully first to make sure you're rewriting it properly?

AsafGartner

But I would say that if you're rewriting some code, you should probably read it carefully first to make sure you're rewriting it properly?

Probably, but skimmability might shrink that time too

Just to provide a little extra context, here is Asaf's original topic pitch: https://github.com/AsafGartner/hmn_fishbowl/discussions/1

Code skimmability as the root cause for bad code structure decision...

1

10:05

And I'll quote the thesis here:

Code doesn't need to be skimmable, because no one should be skimming code. You should either read it carefully or skip it entirely. You don't want to end up in a situation where you think you understand the code when you actually don't. Once you give up on skimmability, you can focus on writing code that is clear when the programmer sits down to read it carefully, but you don't need to make it readable at a glance. A lot of classical readability constraints go away. Much of today's code readability ideas, of having small classes/functions/files, only aid in skimmability.

Note that Asaf is not saying that you don't want code to be readable, but that our notion of "readability" may be off and not helpful.

How do you know you understand the code if you only skimmed it?

10:06

Yes ^

10:06

I'm saying that readability and skimmability are different things.

I would like to explore that difference

Same.

when looking for where you should make the edit having the code be skimmable lets you find the place you are looking for

skimmability is important after you understand the code just to navigate through it

1

ratchetfreak

when looking for where you should make the edit having the code be skimmable lets you find the place you are looking for

Yep thats what I was trying to say

small classes is nice to a point, but it can be done in excess, and i'd argue that extreme amounts of small classes hinders readability if there's no descriptive naming

I think there's a difference between finding your place in the code and understanding the code.

You would skim the code to find your place, but you wouldn't think you understand what you skimmed.

10:09

Which is fine.

AsafGartner

You would skim the code to find your place, but you wouldn't think you understand what you skimmed.

but both fall under skimability and if you try and block the second you necessarily hurt the first

I think you can achieve that level of skimmability with comments or spacing or other things, it doesn't necessarily require changes to the structure of the code. (edited)

10:11

Maybe we should start with a step back a bit. The goal of reading code is to upload/update your mental model of the code.

10:11

Readable code is one that makes that process efficient. First in terms of the integrity of the upload, and second in terms of speed.

2

In my opinion readability is a quality of the code that can only be structured by it's overall architecture/design. It isn't about the geometry, the math behind the code, but more about algorithms and how easy you can recognize them. If you're doing something more complex than it needs to be, than it has bad readability.

Readability requires that the code is easy to tweak/modify. Then If the skimmability achievement is done via separating a piece of code into another function, then I'd say that it can hurt readability, since separation into a function.

Seems like the terminology suggests that reading vs. skimming is about two different LODs... reading => carefully understanding a block of code, skimming => looking at a few non-leaf-nodes of the tree of code briefly (edited)

10:11

So it seems like there's a "spectrum" of readability, and sometimes you want to shift between higher LODs and lower LODs

where are you going with the LOD terminology @ryanfleury ?

Wayward

where are you going with the LOD terminology @ryanfleury ?

Just referring to code as a tree. Sometimes you care about higher level details (stuff higher up in the tree), sometimes you care about specifics (leaf-nodes, lower levels in the tree)

I generally agree with what @ryanfleury said. At a high level you can skim to find your place, but when actually doing work on the code you want the details.

1

10:14

@bumbread exactly. The structure of the code changes to accommodate skimmability, thereby hurting the integrity of the upload.

I like Asaf's breakdown there, so what are aspects that make code better and faster at communicating what is happening?

10:14

For "integrity of the upload", I don't think formatting and whitespace have anything to do with it.

Instead I would think it's more about the structure of the program, how much indirection there is, that kind of thing. Although possibly comments could help in some more confusing cases.

a highly consistent and logical structure used throughout the code, although i'm somewhat confused about why the word integrity is getting dragged into this

consistency in style does help over a project

I'm sure everyone here indents there blocks

in practice I think there's no avoiding skimming