Handmade Network»Fishbowls»Code skimmability as the root cause for bad code structure decisions

Code skimmability as the root cause for bad code structure decisions

Programmers tend to care a lot about "readability". This usually means having small classes, small functions, small files. This code might be "readable" at a glance, but this doesn't really help you understand the programโ€”it's just "skimmable". How can we think about "readability" in a more productive way?

This is a fishbowl: a panel conversation held on the Handmade Network Discord where a select few participants discuss a topic with depth and nuance. We host them every two months, so if you want to catch the next one, join the Discord!
Avatar
Wayward Jan 14, 2021 09:59 AM
Topic: Code skimmability as the root cause for bad code structure decisions
๐Ÿ‘ 5
Avatar
AsafGartner Jan 14, 2021 09:59 AM
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.
Avatar
bumbread Jan 14, 2021 10:01 AM
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
Avatar
AsafGartner Jan 14, 2021 10:02 AM
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
Avatar
Aelthalyste Jan 14, 2021 10:03 AM
But then, if you think there shouldnt be obligation about skimmability, what happens when you refactoring-rewriting some parts of the code
Avatar
AsafGartner Jan 14, 2021 10:03 AM
You might get an idea for what this does without reading it.
Avatar
Aelthalyste Jan 14, 2021 10:03 AM
You may have to put more time than it needs to be
10:03
I think there should be mid point
Avatar
bumbread Jan 14, 2021 10:03 AM
yeah. if/while (something) do some object method calls or field access chain :D
Avatar
AsafGartner Jan 14, 2021 10:04 AM
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.
Avatar
Aelthalyste Jan 14, 2021 10:04 AM
If you like, writing for new codebase, or its a completely new topic to you, you are going to rewrite it
Avatar
Aelthalyste Jan 14, 2021 10:04 AM
and when it happens, you will want to understand the code, without wasting too much time on it
Avatar
AsafGartner Jan 14, 2021 10:04 AM
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?
Avatar
Avatar
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?
Aelthalyste Jan 14, 2021 10:05 AM
Probably, but skimmability might shrink that time too
Avatar
bvisness Jan 14, 2021 10:05 AM
Just to provide a little extra context, here is Asaf's original topic pitch: https://github.com/AsafGartner/hmn_fishbowl/discussions/1
๐Ÿ‘ 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.
Avatar
bvisness Jan 14, 2021 10:06 AM
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.
Avatar
AsafGartner Jan 14, 2021 10:06 AM
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.
Avatar
bvisness Jan 14, 2021 10:07 AM
I would like to explore that difference
Avatar
bumbread Jan 14, 2021 10:07 AM
Same.
Avatar
ratchetfreak Jan 14, 2021 10:07 AM
when looking for where you should make the edit having the code be skimmable lets you find the place you are looking for
Avatar
ratchetfreak Jan 14, 2021 10:07 AM
skimmability is important after you understand the code just to navigate through it
๐Ÿ’ฏ 1
Avatar
Avatar
ratchetfreak
when looking for where you should make the edit having the code be skimmable lets you find the place you are looking for
Aelthalyste Jan 14, 2021 10:08 AM
Yep thats what I was trying to say
Avatar
Wayward Jan 14, 2021 10:07 AM
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
Avatar
AsafGartner Jan 14, 2021 10:08 AM
I think there's a difference between finding your place in the code and understanding the code.
Avatar
AsafGartner Jan 14, 2021 10:09 AM
You would skim the code to find your place, but you wouldn't think you understand what you skimmed.
10:09
Which is fine.
Avatar
Avatar
AsafGartner
You would skim the code to find your place, but you wouldn't think you understand what you skimmed.
ratchetfreak Jan 14, 2021 10:10 AM
but both fall under skimability and if you try and block the second you necessarily hurt the first
Avatar
AsafGartner Jan 14, 2021 10:10 AM
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
Avatar
bumbread Jan 14, 2021 10:09 AM
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.
Avatar
bumbread Jan 14, 2021 10:13 AM
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.
Avatar
ryanfleury (audience) Jan 14, 2021 10:11 AM
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
Avatar
Wayward Jan 14, 2021 10:12 AM
where are you going with the LOD terminology @ryanfleury ?
Avatar
Avatar
Wayward
where are you going with the LOD terminology @ryanfleury ?
ryanfleury (audience) Jan 14, 2021 10:12 AM
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)
Avatar
AsafGartner Jan 14, 2021 10:13 AM
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.
Avatar
bvisness Jan 14, 2021 10:14 AM
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.
Avatar
bvisness Jan 14, 2021 10:15 AM
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.
Avatar
Wayward Jan 14, 2021 10:15 AM
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
Avatar
ratchetfreak Jan 14, 2021 10:15 AM
consistency in style does help over a project
Avatar
ratchetfreak Jan 14, 2021 10:16 AM
I'm sure everyone here indents there blocks
Avatar
demetrispanos (audience) Jan 14, 2021 10:13 AM
in practice I think there's no avoiding skimming
10:13
it's just not how brains work, to either completely ignore something or to read it linearly in detail
10:13
in fact, the natural human behavior is the opposite
10:14
progressive investment of attention based on low-cost cues looking for valuable information
Avatar
ryanfleury (audience) Jan 14, 2021 10:14 AM
Yeah, it seems like you want a knob, and often times you'll want that knob tuned down (to only view high level details) to skim around/find your place
10:14
And then if you want to carefully read a procedure, dial that knob up, see closer details
10:15
To the consistency point, having a consistent language you use in a codebase helps a lot I find
10:16
For example, one thing I've adopted recently is any time you have "conversions" between types (or implied types), e.g. extracting information, I use XFromY naming
10:16
e.g. StringFromNode, ChildFromString, ChildFromStringAndTag
Avatar
demetrispanos (audience) Jan 14, 2021 10:16 AM
in fact, even when you're "reading deeply" you're still skimming, your brain won't let you do anything else
10:16
I'm sure you've had the experience of re-reading a paragraph 10 times to proofread
Avatar
ryanfleury (audience) Jan 14, 2021 10:16 AM
Oh yeah
Avatar
demetrispanos (audience) Jan 14, 2021 10:16 AM
and you just don't see the misspelling, because your brain assumes it's correct
Avatar
AsafGartner Jan 14, 2021 10:16 AM
So, I think some of the problem is with the programmer. There's a natural tendency to skim (as @demetrispanos mentioned) and it's useful to notice when it happens.
Avatar
ratchetfreak Jan 14, 2021 10:16 AM
skimming will always happen when you think you know the code well enough
10:17
you aren't going to detail read the same function a dozen times over
Avatar
bumbread Jan 14, 2021 10:18 AM
I usually skim the code until I find the relevant piece and then read that piece (5-10 lines) carefully, if i need to.
Avatar
AsafGartner Jan 14, 2021 10:18 AM
True. The main difference should be when writing the code. The goal should be to make it easy to read for someone who is paying attention, not to make the code look pretty/simple at a glance.
Avatar
Avatar
AsafGartner
True. The main difference should be when writing the code. The goal should be to make it easy to read for someone who is paying attention, not to make the code look pretty/simple at a glance.
ratchetfreak Jan 14, 2021 10:18 AM
but for a practiced person those end up being correlated
Avatar
rexollycounty Jan 14, 2021 10:18 AM
i think this is often why people have syntax highlighting in their code, it helps navigate easier. i find i will get lost (even when i know the code well) if there aren't hints like whitespace or highlighting
Avatar
bvisness Jan 14, 2021 10:18 AM
I still think there's a worthwhile distinction between "readable" and "skimmable". In terms of prose, I would consider readable text to be concise and clear, explaining things well. Where skimmable text is more about the structure, paragraph breaks, headings, that kind of thing.
๐Ÿ’ฏ 4
10:18
Those are mostly independent.
Avatar
rexollycounty Jan 14, 2021 10:19 AM
so skimmable would fall in the category more with pure presentation?
Avatar
Wayward Jan 14, 2021 10:20 AM
i'm thinking more along the lines of code should be friendly towards manual searching
Avatar
AsafGartner Jan 14, 2021 10:20 AM
@rexollycounty presentation and repetition of that structure across the codebase.
10:20
And consistency of density (usually low density).
Avatar
demetrispanos (audience) Jan 14, 2021 10:19 AM
regarding ben's point, one can analogize to good paragraph structure
10:19
a paragraph supports skimming if the first sentence gives you a good understanding of what you'll find in the rest (so you can decide, with low cost, if you need to read the whole thing)
10:20
if a paragraph jumps around to unrelated subjects, or separates subjects from modifiers with a large distance or whatever, then the spatial structure of the paragraph is fighting your desire to extract information efficiently
Avatar
ryanfleury (audience) Jan 14, 2021 10:21 AM
That makes a lot of sense; in a sense a paragraph is giving you a good setup for good decompression of a skim (edited)
10:21
It gives you hints for predicting what is in the meat of the paragraph
10:22
Which means your skimming will work more for you, less wasteful of a decompression of the language
10:23
On syntax highlighting---and this is something I want to do in my 4coder custom layer (and Dion)---I am really interested in different "visors" (language stolen from @Allen4th) when viewing code.
10:24
Often times, syntax highlighting is just this rainbow of colors, and it washes out all the meaning.
10:24
But if you could turn on, for example, no syntax highlighting except for function calls, or the same with macros, etc.
10:24
That might be a lot more useful.
10:25
Basically I want:
typedef u32 SyntaxFlags; enum { SyntaxFlag_Functions = (1<<0), SyntaxFlag_Macros = (1<<1), SyntaxFlag_Literals = (1<<2), SyntaxFlag_ExternalCode = (1<<3), SyntaxFlag_CommentUserNames = (1<<4), // etc. };
(edited)
10:25
And then a way to turn each of these on/off independently
Avatar
Avatar
rexollycounty
i think this is often why people have syntax highlighting in their code, it helps navigate easier. i find i will get lost (even when i know the code well) if there aren't hints like whitespace or highlighting
Aelthalyste Jan 14, 2021 10:20 AM
Highly disagree, I never navigate through code by just help of the syntax highlighting, your IDE helps lot more than that
10:21
When exploring and searching for particular block in your codebase
Avatar
ratchetfreak Jan 14, 2021 10:21 AM
goto definition and stuff
Avatar
bumbread Jan 14, 2021 10:21 AM
I would like extend @bvisness's definition of skimmability by pointing out that what's important isn't whether skimmability is good, but what tools should and shouldn't we use in order to achieve skimmability
Avatar
Aelthalyste Jan 14, 2021 10:21 AM
synax high helps may help readability, i dont think it helps skimmability (edited)
Avatar
ratchetfreak Jan 14, 2021 10:22 AM
sure it does, seeing the keywords highlighted draws the eye and it can then help your brain label them as what they are
Avatar
Avatar
Aelthalyste
Highly disagree, I never navigate through code by just help of the syntax highlighting, your IDE helps lot more than that
rexollycounty Jan 14, 2021 10:22 AM
in 4coder, things like //NOTE and //HACK are highlighted differently and that often helps me a lot when just skimming so i know what I need to do look at
10:23
and like, if i have a block comment without highlighting it's not obvious when skimming if that's code or not
Avatar
Aelthalyste Jan 14, 2021 10:23 AM
These things helps how you read code
Avatar
Avatar
rexollycounty
and like, if i have a block comment without highlighting it's not obvious when skimming if that's code or not
Aelthalyste Jan 14, 2021 10:24 AM
fair point
Avatar
ratchetfreak Jan 14, 2021 10:24 AM
they also help in jumping to different parts of the code and getting a grasp of the basic structure at a glance
Avatar
rexollycounty Jan 14, 2021 10:24 AM
if i skim something, the only thing highlighted in red will be //NOTE and that's very obvious when scrolling quickly through a big file
Avatar
AsafGartner Jan 14, 2021 10:23 AM
I just want to point out that skimmability is bad only when you think you understand the code that you just skimmed without having read it properly.
Avatar
Avatar
AsafGartner
I just want to point out that skimmability is bad only when you think you understand the code that you just skimmed without having read it properly.
bumbread Jan 14, 2021 10:24 AM
What might the consequences of that be ?
Avatar
ratchetfreak Jan 14, 2021 10:24 AM
bugs
Avatar
AsafGartner Jan 14, 2021 10:24 AM
Yes.
Avatar
ratchetfreak Jan 14, 2021 10:25 AM
if you don't understand the code you will make mistakes when editing it
Avatar
AsafGartner Jan 14, 2021 10:25 AM
You think you understand it, you make changes based on that understanding, and you miss all the edge cases.
10:25
Or sometimes even the main cases.
Avatar
ratchetfreak Jan 14, 2021 10:25 AM
IME edge cases take up more code area than the main cases though
Avatar
Avatar
AsafGartner
You think you understand it, you make changes based on that understanding, and you miss all the edge cases.
bvisness Jan 14, 2021 10:25 AM
This is very common, by the way, when you work on a larger codebase and frequently have to make changes to areas you have never touched before.
Avatar
ratchetfreak Jan 14, 2021 10:25 AM
to the point they can obscure the main case
Avatar
AsafGartner Jan 14, 2021 10:28 AM
This may be going a bit into information theory (and I am no expert in that), but if you could properly understand a thing by skimming it, doesn't it make it extremely redundant?
Avatar
ratchetfreak Jan 14, 2021 10:29 AM
there is already a bunch of redundancy in code
10:29
it's what makes it so compressible
Avatar
bumbread Jan 14, 2021 10:30 AM
I could skim through this:
int min = a[0]; for(int i = 1; i < arr_len; i += 1) { if(a[i] < min) min = a[i]; }
and understand what the piece of code does without cheking the signs and stuff.
10:30
The bug could be hiding if i put the comparison sign the wrong way, and my skimming would be totally off
10:30
Or if i named the variable differently (ex: max)
10:31
the question is how do you get rid of this and should you
10:31
most people will put this sort of thing out into a function
Avatar
Aelthalyste Jan 14, 2021 10:32 AM
but putting it into a function doesn't make bug/error disappear or makes it clearly observable while skimming
๐Ÿ’ฏ 1
10:32
it just compress error point to fixed one (edited)
10:32
instead of bunch of many
Avatar
AsafGartner Jan 14, 2021 10:33 AM
I think the distinction makes more sense in more involved pieces of code.
10:34
There's just not much going on in @bumbread's example.
Avatar
Avatar
bumbread
I could skim through this:
int min = a[0]; for(int i = 1; i < arr_len; i += 1) { if(a[i] < min) min = a[i]; }
and understand what the piece of code does without cheking the signs and stuff.
bumbread Jan 14, 2021 10:34 AM
10:34
:)
Avatar
AsafGartner Jan 14, 2021 10:34 AM
That is, you already have that bit of code in your head somewhere, because we all wrote it at some point.
10:34
And so in this case filling in after skimming doesn't result in a mistake.
Avatar
bvisness Jan 14, 2021 10:35 AM
@AsafGartner It might be worth looking at some code examples.
10:35
We had discussed a couple before this fishbowl
Avatar
Wayward Jan 14, 2021 10:35 AM
i'd have to agree to that
Avatar
ratchetfreak Jan 14, 2021 10:35 AM
having good grasp of the idioms used in the project will improve skimmability because each idiom is a pattern that can be mentally matched against
Avatar
bumbread Jan 14, 2021 10:35 AM
stb stretchy buffer was proposed as one such example
Avatar
bumbread Jan 14, 2021 10:36 AM
it fits on one screenfull of code
Avatar
Aelthalyste Jan 14, 2021 10:36 AM
stretchy buffer is a good starting point
Avatar
AsafGartner Jan 14, 2021 10:36 AM
Right, so stretchy does two things.
10:36
First of all, it's highly compressed, which I don't think is a requirement.
10:37
But even uncompressed it would be fairly compact and require careful reading.
10:37
If you compare that to more OOPy implementations of the same thing, those tend to be very long and very sparse.
Avatar
Aelthalyste Jan 14, 2021 10:38 AM
and they wouldnt be skimmable, probably
Avatar
AsafGartner Jan 14, 2021 10:38 AM
They would be skimmable. You would be able to look at each part of it and it would seem understandable.
10:39
Like, some get(index) function isn't going to make you sweat.
Avatar
Aelthalyste Jan 14, 2021 10:39 AM
Of course not, but hiding your problem behind some obscure things is not gonna help you
Avatar
AsafGartner Jan 14, 2021 10:39 AM
Exactly.
Avatar
Aelthalyste Jan 14, 2021 10:39 AM
It would take more mental time-effort to make reasonable picture of it, at least for me
Avatar
Avatar
AsafGartner
If you compare that to more OOPy implementations of the same thing, those tend to be very long and very sparse.
bumbread Jan 14, 2021 10:39 AM
I wonder if that's because people want to put "a name" on pieces of code. Like the same reason you would separate something into a function in order to give that functionality a name. In which case the more involved the piece of code is, the more names it will have. Then isn't it better if you have a more consise code, but instead of separating into functions to put some comments in?
Avatar
rexollycounty Jan 14, 2021 10:40 AM
i wonder if some of the motivations behind oop were so that UML diagrams could be used to make it easier to skim
Avatar
ratchetfreak Jan 14, 2021 10:41 AM
UML definitely supported the OOP mindset
Avatar
AsafGartner Jan 14, 2021 10:41 AM
@bumbread but why do they want that?
Avatar
bumbread Jan 14, 2021 10:41 AM
"readability"/skimmability
Avatar
Wayward Jan 14, 2021 10:41 AM
it was the hype at the time
Avatar
ratchetfreak Jan 14, 2021 10:42 AM
UML was supposed to make large complex projects understandable to the layman
Avatar
Aelthalyste Jan 14, 2021 10:42 AM
but time you spend on making UML, you can make proper code structure that is actually easy to skim
Avatar
Aelthalyste Jan 14, 2021 10:42 AM
rather than just trying to solve problem, make it dissappear at the first place
Avatar
bumbread Jan 14, 2021 10:42 AM
I don't think those kinds of people appreciate what i call "a flat code". The stupid code that literally does the things it has to do in order to do what it needs to do. No indirections, no complications.
Avatar
rexollycounty Jan 14, 2021 10:43 AM
i think that's part of forcing your code structure to change in order to make it skimmable, which in this case has been a bad idea
๐Ÿ’ฏ 1
Avatar
bvisness Jan 14, 2021 10:43 AM
No indirections, no complications.
Indirection is certainly part of it. I think breaking things into many small pieces frequently harms readability by not making execution flow clear. But the same code might be considered "skimmable" by many because it's easy to find a specific piece by name.
Avatar
AsafGartner Jan 14, 2021 10:43 AM
@Aelthalyste I think your concept of skimmability is kind of what I mean by readability. I don't think code needs to be unnecessarily difficult, but many programmers just go in the complete opposite direction, where code is made up of tiny pieces that are each "pleasant", but don't easily come together to make a complete and understandable whole.
Avatar
Wayward Jan 14, 2021 10:44 AM
i view UML etc more of a "tool" invented to talk to incompetent people in leadership positions
Avatar
ratchetfreak Jan 14, 2021 10:46 AM
don't pull things out into functions when they don't need to be
Avatar
ratchetfreak Jan 14, 2021 10:46 AM
I dislike std::algorithm style code for that reason, it obscures what actually happens behind a name and janky lambda syntax
Avatar
Avatar
AsafGartner
@Aelthalyste I think your concept of skimmability is kind of what I mean by readability. I don't think code needs to be unnecessarily difficult, but many programmers just go in the complete opposite direction, where code is made up of tiny pieces that are each "pleasant", but don't easily come together to make a complete and understandable whole.
rexollycounty Jan 14, 2021 10:46 AM
i think this is an interesting problem that something like dion could solve. for an example of having a function which is composed of lots more function calls that are all in different 'files' there was some idea of being able to inline them in the editor so that you can see the flow of code better without any indirections
Avatar
AsafGartner Jan 14, 2021 10:47 AM
@Voran that's a bit of a tough question. One thing, that for me seems fairly easy, but other programmers told me they can't do it as easily, is to try to understand the dependencies of each chunk of code, and try not to put them too far away.
Avatar
Avatar
AsafGartner
@bumbread but why do they want that?
bumbread Jan 14, 2021 10:51 AM
oh and another reason is probably being afraid of repeating oneself. If the same piece of code is written at least twice some will be likely to pull it out into a separate function
Avatar
Wayward Jan 14, 2021 10:52 AM
that sounds like a case of excessive segregation
Avatar
Avatar
bumbread
oh and another reason is probably being afraid of repeating oneself. If the same piece of code is written at least twice some will be likely to pull it out into a separate function
Aelthalyste Jan 14, 2021 10:52 AM
Don't make things functions unless you are sure that these codepaths exactly want same things
Avatar
Aelthalyste Jan 14, 2021 10:53 AM
Often, when compressing code in order to make it readable-skimmable, we might miss that part (edited)
Avatar
bumbread Jan 14, 2021 10:53 AM
Right.
10:53
Changing that function then may result in a change for codepaths that wanted different things from that function thus making a bug
Avatar
Aelthalyste Jan 14, 2021 10:53 AM
exactly
Avatar
bvisness Jan 14, 2021 10:54 AM
That is a really good example of a situation where "skimmability" hurts. It's common to think you can "reuse" something from elsewhere in the code, because it is out on its own and has a name that seems similar to what you want. But later you find out that it was being used for a different purpose and things get ugly.
10:55
Well, maybe I shouldn't say that skimmability hurt, but rather the decision to pull it out into its own function for the sake of skimmability
Avatar
Avatar
bvisness
That is a really good example of a situation where "skimmability" hurts. It's common to think you can "reuse" something from elsewhere in the code, because it is out on its own and has a name that seems similar to what you want. But later you find out that it was being used for a different purpose and things get ugly.
Aelthalyste Jan 14, 2021 10:57 AM
Yes, targeting for skimmability might hurt codebase. @AsafGartner what I mean by skimmability here is, compressing for tiny textual information helps you to skip bunch of code. Rather than seeing 10 lines of operations, you can see 2-3 line of information and this scale non-linearly
Avatar
bumbread Jan 14, 2021 10:57 AM
So far we have discussed how segregating the code into functions, while improving skimability, can decrease readability and mantainability. Are there any other factors that potentially improve skimmability?
Avatar
ratchetfreak Jan 14, 2021 10:58 AM
having the correct brace style
Avatar
bumbread Jan 14, 2021 10:58 AM
What is "the correct brace style"?
10:58
1TBS?
10:58
Exactly
Avatar
AsafGartner Jan 14, 2021 11:00 AM
@Aelthalyste if you skip code, I think that's fine. If you end up with an impression that you understand what you skimmed, that's a recipe for disaster. I agree that you don't want an excessive amount of code or code that doesn't make it clear when a meaningful piece ends.
Avatar
bumbread Jan 14, 2021 11:01 AM
But we shouldn't turn that into a rule, "don't ever segregate the code since it can decrease the other factors". Rather, we should understand why this happens and have a more concrete: "... don't do it prematurely" part.
Avatar
Aelthalyste Jan 14, 2021 11:01 AM
but problem starts at "maturely" part @bumbread
11:01
isnt it?
Avatar
AsafGartner Jan 14, 2021 11:02 AM
I think my general rule is: write for an attentive reader.
Avatar
Avatar
AsafGartner
@Aelthalyste if you skip code, I think that's fine. If you end up with an impression that you understand what you skimmed, that's a recipe for disaster. I agree that you don't want an excessive amount of code or code that doesn't make it clear when a meaningful piece ends.
Aelthalyste Jan 14, 2021 11:03 AM
Yes, skip is the thing you want to do
๐Ÿ’ฏ 1
Avatar
bumbread Jan 14, 2021 11:04 AM
usually the grouping is done via scope blocks and comments, or separating the chunks with new lines
Avatar
rexollycounty Jan 14, 2021 11:05 AM
im not sure if it has been said, but often comments are an issue for skimmability because theres the assumption that the comment is correct and up to date
Avatar
bumbread Jan 14, 2021 11:05 AM
here's a part of my codebase. Here i used a combination of code blocks and whitespace to group the relevant parts
11:05
actually some people would pull those parts into several functions, which is wrong imo
Avatar
Avatar
rexollycounty
im not sure if it has been said, but often comments are an issue for skimmability because theres the assumption that the comment is correct and up to date
bvisness Jan 14, 2021 11:06 AM
I might extend this beyond comments, actually. Code may be edited long after it's written in ways that conflict with the existing names and structure.
11:06
So there you run the risk of your skim being out of date.
11:11
When we were prepping this fishbowl, the thought of code going out of date hadn't occurred to me, and I think it's actually quite relevant to this topic. I've often seen the advice that you should make your code "readable", because comments go out of date and such. But this notion is also true at a larger scale.
Avatar
bvisness Jan 14, 2021 11:12 AM
Chunking a program down into many small functions or files feels to me exactly the same as excessively commenting your code. It's just at a scale larger than one function or class.
11:12
It's subject to exactly the same kinds of failures.
Avatar
bvisness Jan 14, 2021 11:12 AM
And all in the name of "readability"
Avatar
ratchetfreak Jan 14, 2021 11:12 AM
dead code can linger for a long time
Avatar
ratchetfreak Jan 14, 2021 11:12 AM
the effective comment is the name of the function
Avatar
ratchetfreak Jan 14, 2021 11:12 AM
which can go out of data as well
11:13
comments if there should explain why the code is the way it is and why not another way
Avatar
rexollycounty Jan 14, 2021 11:12 AM
i pretty much exclusively use comments to tell me what to add/change rather than describe the code. to me having comments that describe the code just feels like writing the code twice
Avatar
AsafGartner Jan 14, 2021 11:14 AM
How often do you see out of date comments?
Avatar
bvisness Jan 14, 2021 11:15 AM
Less often than out of date names
11:15
especially in the dynamic language world, oh my goodness
Avatar
ratchetfreak Jan 14, 2021 11:15 AM
in my code? not often at all because I don't leave comments
Avatar
bvisness Jan 14, 2021 11:15 AM
"oh, two years ago we just started passing some other data in here? cool, cool"
Avatar
bumbread Jan 14, 2021 11:16 AM
my comments were helping my little brain understand the nature of doubly linked lists i used for directory contents storage :D
Avatar
Avatar
bvisness
Less often than out of date names
AsafGartner Jan 14, 2021 11:16 AM
One day we should do a fishbowl about code honesty.
11:17
i think this is probably one of the worst pieces of code i've ever had to work with
11:17
it pretty much fails in every department as far as i'm concerned
Avatar
bvisness Jan 14, 2021 11:17 AM
Wow, that's a special case. Huge comments, and tiny variable names. (edited)
Avatar
bumbread Jan 14, 2021 11:17 AM
oh got it
11:17
input/output
Avatar
Avatar
bvisness
Wow, that's a special case. Huge comments, and tiny variable names. (edited)
bumbread Jan 14, 2021 11:18 AM
11:18
ha
Avatar
rexollycounty Jan 14, 2021 11:18 AM
i had to port this to gpu and so i just had to ignore everything in the code because it was either misleading or just wrong
Avatar
bvisness Jan 14, 2021 11:19 AM
I guess naming is another aspect of readability that we could discuss
11:19
although I'm not sure it relates to skimmability at all
11:19
maybe within a function, but that's a less interesting level to me
Avatar
rexollycounty Jan 14, 2021 11:19 AM
it definitely meant i could make zero assumptions about the code
Avatar
bumbread Jan 14, 2021 11:19 AM
Yes. I have experience of naming every variable with underscores in my homework assignment for my programming course. I named the first variable _, the next one __ &c.
Avatar
Avatar
bumbread
Yes. I have experience of naming every variable with underscores in my homework assignment for my programming course. I named the first variable _, the next one __ &c.
bumbread Jan 14, 2021 11:20 AM
The effect of this, is that you have to do A LOT of extra state keeping in order to understand your code. I gave up writing insertion sort algorithm that way, I had to do normal naming
11:20
That's about the extremes.
Avatar
ratchetfreak Jan 14, 2021 11:20 AM
cryptic names are a pain
Avatar
AsafGartner Jan 14, 2021 11:20 AM
Well, you don't want to send the reader all over place.
Avatar
Aelthalyste Jan 14, 2021 11:20 AM
You shouldnt be reading names or such things when skimming, that's just reading the code
Avatar
AsafGartner Jan 14, 2021 11:20 AM
A good upload has good references.
Avatar
Avatar
bumbread
The effect of this, is that you have to do A LOT of extra state keeping in order to understand your code. I gave up writing insertion sort algorithm that way, I had to do normal naming
rexollycounty Jan 14, 2021 11:22 AM
that's a good way of putting it. when reading cryptic vairable names, having seemingly unrelated names makes it hard to keep track of
Avatar
bvisness Jan 14, 2021 11:24 AM
The counterpoint, perhaps, is that sometimes a name is used so frequently, or has a meaning so obvious, that a longer name would make the code less concise. Like having a sentence be too wordy.
Avatar
ratchetfreak Jan 14, 2021 11:24 AM
like i for an int index
Avatar
Aelthalyste Jan 14, 2021 11:24 AM
I think naming and frequency of variable is highly dependent
11:25
Like, you know what's an i in for loop, its used everywhere
11:25
but you dont want some cryptic name in just one specific point-line
Avatar
ratchetfreak Jan 14, 2021 11:25 AM
in my work project I have a set of 3 letter variables that I use all over the place and every time I use them they always mean the same
Avatar
Aelthalyste Jan 14, 2021 11:25 AM
You want it's name to express what it represents, what it means (edited)
Avatar
ratchetfreak Jan 14, 2021 11:26 AM
though really that is more of a result of having started that project in a deep OOP mindset
Avatar
rexollycounty Jan 14, 2021 11:26 AM
casey has a LockedAddAndReturnPreviousValue in handmade ray and i've always wondered whether it's too long
Avatar
Avatar
rexollycounty
casey has a LockedAddAndReturnPreviousValue in handmade ray and i've always wondered whether it's too long
AsafGartner Jan 14, 2021 11:28 AM
Sounds like a trustworthy name.
Avatar
Aelthalyste Jan 14, 2021 11:33 AM
on tangent, I don't think name length or convention is the real bottleneck about reading-understanding code. They mean to represent things in larger scale, for few blocks. Context they belong to should be enough for you to identify what's happening in relevant block-function
Avatar
ratchetfreak Jan 14, 2021 11:34 AM
there is such a thing as too long though
Avatar
Aelthalyste Jan 14, 2021 11:35 AM
Let's say, if you have something like 500 line function, having some 3 letter name is not actual bottleneck here, or 30. 500 lines itself can bring too much friction
Avatar
AsafGartner Jan 14, 2021 11:35 AM
Sometimes I just do short = veryLongName and use short in that specific area of the code.
Avatar
Avatar
AsafGartner
Sometimes I just do short = veryLongName and use short in that specific area of the code.
Aelthalyste Jan 14, 2021 11:36 AM
Yes, variables-names should have strict contexts to be compared.
Avatar
AsafGartner Jan 14, 2021 11:37 AM
And the length of the variable name should probably match the length of the context.
Avatar
bumbread Jan 14, 2021 11:37 AM
Agree
11:38
It is easier to keep track of short names in short scopes
Avatar
Avatar
AsafGartner
And the length of the variable name should probably match the length of the context.
Aelthalyste Jan 14, 2021 11:38 AM
Exactly
Avatar
AsafGartner Jan 14, 2021 11:38 AM
You wouldn't want to juggle two-letter variables for 500 lines.
Avatar
bumbread Jan 14, 2021 11:38 AM
Also adds a layer of style conventions
Avatar
AsafGartner Jan 14, 2021 11:39 AM
I mean, it's more or less like a CPU cache.
11:39
If the name of the variable doesn't make the usage very clear, you'll have to look it up.
11:40
How far up do you have to scroll in order to look it up?
11:40
If it's too much, the name is too short.
Avatar
Aelthalyste Jan 14, 2021 11:40 AM
In short contextes, its L1 cache anyway
11:40
and you are probably using registers (edited)
Avatar
bumbread Jan 14, 2021 11:41 AM
By the way remember how i told that confusing names tend to do extra state-keeping for the mind? I think that's actually good if you have short names for short, more specific pieces of the code, and longer names for the less specific pieces. Since your mind will be actually into reading the code rather than skimming on the low level
Avatar
AsafGartner Jan 14, 2021 11:42 AM
I think that in many cases reading longer variable names is "free".
11:43
Writing them is not as free.
11:43
Or if you have several of them in a single line that it runs off the screen, that's not free either.
11:43
But in most cases it's free to read.
11:43
So I would optimize Dion-like systems to make writing cheaper, but expand the names for reading.
Avatar
bumbread Jan 14, 2021 11:43 AM
but on the other hand most likely you'll be having more of specific code than abstract code, which makes it so that you are rarely typing long names
11:44
Making it less expensive to write long names in long contexts (?)
Avatar
ratchetfreak Jan 14, 2021 11:46 AM
autocompletion, maybe based on initials, prefix, manual alias, etc.
11:47
highlighting itself is going to be a cost
11:48
and the tradeoff balance is going to be different case to case
๐Ÿ‘ 1
Avatar
AsafGartner Jan 14, 2021 11:49 AM
Once you introduce dynamic information you'll need a more powerful editor.
11:50
So it's not entirely a code thing.
11:50
Though I hear people liked the feature in the Kindle that reminds you of character's backstory when you highlight them.
11:50
So a similar feature would probably be useful.
11:53
Do you think future editors/system would dramatically change the way we approach reading code?
11:53
The idea of slices in Dion sounds very interesting, but without trying it out it's hard to say.
Avatar
Avatar
AsafGartner
Do you think future editors/system would dramatically change the way we approach reading code?
Aelthalyste Jan 14, 2021 11:56 AM
I mean, if intellisense(or something close to that) would be 100x faster, they might be
Avatar
AsafGartner Jan 14, 2021 11:58 AM
I think it would be interesting to see what sort of effect it would have on code structure.
11:58
Maybe you wouldn't mind spreading code around if you could recall it into a single slice?
Avatar
Aelthalyste Jan 14, 2021 12:01 PM
So there was a good point stb put in this video https://www.youtube.com/watch?v=eAhWIO1Ra6M, IDE might help you shortcutting to some paths (edited)
Avatar
AsafGartner Jan 14, 2021 12:04 PM
Yeah, it would be interesting to see how it all works out. It's really hard to predict that stuff in advance.
12:04
Another thing I wanted to talk about, and another positive thing you can do: I think code appearance is a metric all on its own. It's possible to make a complicated piece of code appear simple by hiding everything behind far-away functions/classes, and you can make a simple piece of code appear complicated with unnecessary indirection. Instead you should make your code appear as complicated as it actually is.
Avatar
Aelthalyste Jan 14, 2021 12:06 PM
I was curious when we were going to get to this
12:06
I want to start from file level appearance
Avatar
bumbread Jan 14, 2021 12:07 PM
I can describe how stb stretchy buffer works in 3-10 lines of text, but the code for that looks more complicated than that.
12:08
Most of the code is the macro hacks though
Avatar
Aelthalyste Jan 14, 2021 12:08 PM
I think you should have very strict context switches between files
Avatar
Avatar
Aelthalyste
I think you should have very strict context switches between files
bumbread Jan 14, 2021 12:08 PM
What do you mean by context switches?
Avatar
Aelthalyste Jan 14, 2021 12:10 PM
Like, solving kinematic equations and dumping all things to a file
12:11
Solving kinematics involves multiple things, mostly math stuff. You don't want to end up reading file
FileOps.cpp
at the end of the result
Avatar
Avatar
bumbread
I can describe how stb stretchy buffer works in 3-10 lines of text, but the code for that looks more complicated than that.
AsafGartner Jan 14, 2021 12:11 PM
In the case of stb stretchy, I think there's an element of expectation and also an element of trusting the author. I know it's compressed, so I know it will take longer than usual to read what look like a few lines of code, and I trust Sean to not waste my time with something that's just a big mess.
Avatar
Aelthalyste Jan 14, 2021 12:11 PM
or,
kinematics.cpp
shouldnt make indirection to must-read code that lies in
fileops.cpp
(edited)
12:14
because at the top level, files significiantly helps skimming. You can choose them as very top level entry for a codebase
Avatar
AsafGartner Jan 14, 2021 12:15 PM
Right. You want to direct the reader to the right place, and not have them search for a needle in a haystack.
Avatar
Aelthalyste Jan 14, 2021 12:15 PM
they can make references to each other, but they should be self-contained enough to be understanable
12:15
Even simple point like this is misused so much
12:16
Like recent bug Casey discovered on stream (i dont remember program's name, OBS? was some video capture program) (edited)
12:17
Same context, exactly same problem's solution is directed to different files. Which can be just 30 line function
Avatar
AsafGartner Jan 14, 2021 12:18 PM
Right. I saw that one, but unfortunately it's not on youtube.
12:18
The structure of OBS is one of the things that prompted this fishbowl idea.
12:20
It gives the impression that everything has a right place, and each part is simple, but also that there are many parts, but actually it's juggling several pieces of very important data from different places, and it makes it very easy to miss the important details. (edited)
Avatar
Aelthalyste Jan 14, 2021 12:20 PM
File switches are like warnings to me, be aware that you are going different world, not that it's harmful, just be aware (edited)
12:23
and about hiding things behind classes-methods-private members, I think that is discussed long enough in that server, even in code-readability section
Avatar
AsafGartner Jan 14, 2021 12:25 PM
I think that's all I have to say on this topic. Any last notes?
Avatar
rexollycounty Jan 14, 2021 12:26 PM
that's all from me too (edited)
Avatar
Aelthalyste Jan 14, 2021 12:27 PM
I'm just tired
Avatar
AsafGartner Jan 14, 2021 12:27 PM
:)
Avatar
bvisness Jan 14, 2021 12:28 PM
This was a good conversation, I think we hit on some interesting points
Avatar
AsafGartner Jan 14, 2021 12:29 PM
So that's a wrap on Fishbowl #5. Thank you all for joining us. You can go to https://github.com/AsafGartner/hmn_fishbowl/discussions to vote on the next fishbowl topic and suggest new ones.
Contribute to AsafGartner/hmn_fishbowl development by creating an account on GitHub.
Avatar
bvisness Jan 14, 2021 12:30 PM
Future readers, if you're interested in reading the #fishbowl-audience conversation too, see https://discord.com/channels/239737791225790464/708458209131757598/799323988769636463. There was some great stuff over there! (edited)
12:31
Thanks all for participating!
Avatar
bvisness Jan 14, 2021 12:45 PM
If you would like to read the whole conversation from the beginning, check the pinned messages. There are also several other conversations for you to read if you're interested!