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?
Topic: Code skimmability as the root cause for bad code structure decisions
5
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
1
skimmability is important after you understand the code just to navigate through it
1
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
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
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
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
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.
but for a practiced person those end up being correlated
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
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
Highly disagree, I never navigate through code by just help of the syntax highlighting, your IDE helps lot more than that
Highly disagree, I never navigate through code by just help of the syntax highlighting, your IDE helps lot more than that
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
and like, if i have a block comment without highlighting it's not obvious when skimming if that's code or not
fair point
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.
What might the consequences of that be ?
You think you understand it, you make changes based on that understanding, and you miss all the edge cases.
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.
but putting it into a function doesn't make bug/error disappear or makes it clearly observable while skimming
1
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.
it fits on one screenfull of code
If you compare that to more OOPy implementations of the same thing, those tend to be very long and very sparse.
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?
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
@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.
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
@bumbread but why do they want that?
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
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
Don't make things functions unless you are sure that these codepaths exactly want same things
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.
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
@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.
Yes, skip is the thing you want to do
1
here's a part of my codebase. Here i used a combination of code blocks and whitespace to group the relevant parts
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
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.
my comments were helping my little brain understand the nature of doubly linked lists i used for directory contents storage :D
Less often than out of date names
One day we should do a fishbowl about code honesty.
Wow, that's a special case. Huge comments, and tiny variable names.
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.
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
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
that's a good way of putting it. when reading cryptic vairable names, having seemingly unrelated names makes it hard to keep track of
casey has a LockedAddAndReturnPreviousValue in handmade ray and i've always wondered whether it's too long
Sounds like a trustworthy name.
Sometimes I just do short = veryLongName and use short in that specific area of the code.
Yes, variables-names should have strict contexts to be compared.
And the length of the variable name should probably match the length of the context.
Exactly
and the tradeoff balance is going to be different case to case
1
Do you think future editors/system would dramatically change the way we approach reading code?
I mean, if intellisense(or something close to that) would be 100x faster, they might be
I think you should have very strict context switches between files
What do you mean by context switches?
I can describe how stb stretchy buffer works in 3-10 lines of text, but the code for that looks more complicated than that.
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.
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.