diff --git a/src/templates/src/fishbowls/skimming/files/0-EB806.png b/src/templates/src/fishbowls/skimming/files/0-EB806.png new file mode 100644 index 0000000..1655996 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/0-EB806.png differ diff --git a/src/templates/src/fishbowls/skimming/files/1-B2132.png b/src/templates/src/fishbowls/skimming/files/1-B2132.png new file mode 100644 index 0000000..7e644f0 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/1-B2132.png differ diff --git a/src/templates/src/fishbowls/skimming/files/1963eacbf364164efce1c597dc66aeab-E6901.png b/src/templates/src/fishbowls/skimming/files/1963eacbf364164efce1c597dc66aeab-E6901.png new file mode 100644 index 0000000..ccf4824 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/1963eacbf364164efce1c597dc66aeab-E6901.png differ diff --git a/src/templates/src/fishbowls/skimming/files/1f44c-35C6F.svg b/src/templates/src/fishbowls/skimming/files/1f44c-35C6F.svg new file mode 100644 index 0000000..c36d774 --- /dev/null +++ b/src/templates/src/fishbowls/skimming/files/1f44c-35C6F.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/templates/src/fishbowls/skimming/files/1f44d-B3F5F.svg b/src/templates/src/fishbowls/skimming/files/1f44d-B3F5F.svg new file mode 100644 index 0000000..595672d --- /dev/null +++ b/src/templates/src/fishbowls/skimming/files/1f44d-B3F5F.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/templates/src/fishbowls/skimming/files/1f4af-2188D.svg b/src/templates/src/fishbowls/skimming/files/1f4af-2188D.svg new file mode 100644 index 0000000..3d565cc --- /dev/null +++ b/src/templates/src/fishbowls/skimming/files/1f4af-2188D.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/templates/src/fishbowls/skimming/files/40807682-14C1D b/src/templates/src/fishbowls/skimming/files/40807682-14C1D new file mode 100644 index 0000000..8b7c134 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/40807682-14C1D differ diff --git a/src/templates/src/fishbowls/skimming/files/463270-0002E b/src/templates/src/fishbowls/skimming/files/463270-0002E new file mode 100644 index 0000000..6a5cbbb Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/463270-0002E differ diff --git a/src/templates/src/fishbowls/skimming/files/62e486caf24d352ab938701a8d972730-5ADCF.png b/src/templates/src/fishbowls/skimming/files/62e486caf24d352ab938701a8d972730-5ADCF.png new file mode 100644 index 0000000..8c3d6c9 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/62e486caf24d352ab938701a8d972730-5ADCF.png differ diff --git a/src/templates/src/fishbowls/skimming/files/6d80b92b4cf9313aeb1c332b65c48f63-50810.png b/src/templates/src/fishbowls/skimming/files/6d80b92b4cf9313aeb1c332b65c48f63-50810.png new file mode 100644 index 0000000..c60ce89 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/6d80b92b4cf9313aeb1c332b65c48f63-50810.png differ diff --git a/src/templates/src/fishbowls/skimming/files/71ecf1f788f1530928078a8fd18a3111-341F5.png b/src/templates/src/fishbowls/skimming/files/71ecf1f788f1530928078a8fd18a3111-341F5.png new file mode 100644 index 0000000..2cd2aee Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/71ecf1f788f1530928078a8fd18a3111-341F5.png differ diff --git a/src/templates/src/fishbowls/skimming/files/89747c254631bcfd05c5c3e7141389aa-A1FB9.png b/src/templates/src/fishbowls/skimming/files/89747c254631bcfd05c5c3e7141389aa-A1FB9.png new file mode 100644 index 0000000..6fe1dbd Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/89747c254631bcfd05c5c3e7141389aa-A1FB9.png differ diff --git a/src/templates/src/fishbowls/skimming/files/e2d8d41642ab506856842f35a14d0182-CDCD1.png b/src/templates/src/fishbowls/skimming/files/e2d8d41642ab506856842f35a14d0182-CDCD1.png new file mode 100644 index 0000000..9b4f22d Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/e2d8d41642ab506856842f35a14d0182-CDCD1.png differ diff --git a/src/templates/src/fishbowls/skimming/files/e666f2aa4fa50eade7484de6a45639dc-A5D0D.png b/src/templates/src/fishbowls/skimming/files/e666f2aa4fa50eade7484de6a45639dc-A5D0D.png new file mode 100644 index 0000000..89e0d18 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/e666f2aa4fa50eade7484de6a45639dc-A5D0D.png differ diff --git a/src/templates/src/fishbowls/skimming/files/image-59737.png b/src/templates/src/fishbowls/skimming/files/image-59737.png new file mode 100644 index 0000000..053ef36 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/image-59737.png differ diff --git a/src/templates/src/fishbowls/skimming/files/opengraph-563E5.png b/src/templates/src/fishbowls/skimming/files/opengraph-563E5.png new file mode 100644 index 0000000..fcab24a Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/opengraph-563E5.png differ diff --git a/src/templates/src/fishbowls/skimming/files/unknown-1B494.png b/src/templates/src/fishbowls/skimming/files/unknown-1B494.png new file mode 100644 index 0000000..f42e38d Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/unknown-1B494.png differ diff --git a/src/templates/src/fishbowls/skimming/files/unknown-478F3.png b/src/templates/src/fishbowls/skimming/files/unknown-478F3.png new file mode 100644 index 0000000..5558608 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/unknown-478F3.png differ diff --git a/src/templates/src/fishbowls/skimming/files/unknown-CE5DD.png b/src/templates/src/fishbowls/skimming/files/unknown-CE5DD.png new file mode 100644 index 0000000..1d053fb Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/unknown-CE5DD.png differ diff --git a/src/templates/src/fishbowls/skimming/files/unknown-D009E.png b/src/templates/src/fishbowls/skimming/files/unknown-D009E.png new file mode 100644 index 0000000..5440b0e Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/unknown-D009E.png differ diff --git a/src/templates/src/fishbowls/skimming/files/unknown-D8590.png b/src/templates/src/fishbowls/skimming/files/unknown-D8590.png new file mode 100644 index 0000000..2023ad9 Binary files /dev/null and b/src/templates/src/fishbowls/skimming/files/unknown-D8590.png differ diff --git a/src/templates/src/fishbowls/skimming/skimming.html b/src/templates/src/fishbowls/skimming/skimming.html new file mode 100644 index 0000000..38611e5 --- /dev/null +++ b/src/templates/src/fishbowls/skimming/skimming.html @@ -0,0 +1,8614 @@ +
+ + + + + + + + +
+
+
+
+ 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
+
+ +
+ + +
+ + + Image attachment + +
+ + + +
+
+
+
+ + + +
+
+
+
+ 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 +
+ + +
+ + + Image attachment + +
+ + + +
+
+
+
+
+
+
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 + +
+ +
+ + + Image attachment + +
+ + + +
+
+
+
+ + + +
+
+
+
+ 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 + +
+ +
+ + + Image attachment + +
+ + + +
+
+
+
+
+
+
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 + +
+ +
+ + + Image attachment + +
+ + + +
+
+
+
+ + + +
+
+
+
+
+ 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 +
+ +
+ what's i: + +
+ + + + +
+
+
+
+ + + + + + + +
+
+
+
+ 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 +
+ + +
+ + + Image attachment + +
+ + + +
+
+
+
+
+
+
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.
+
+ +
+ +
+ + Thumbnail + +
+
+ + +
+
+ + +
+
+
+
+ + + +
+
+
+
+ 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! + +
+ + + + +
+
+
+
+ + +
\ No newline at end of file diff --git a/src/website/fishbowl.go b/src/website/fishbowl.go index 4670c01..6a3130b 100644 --- a/src/website/fishbowl.go +++ b/src/website/fishbowl.go @@ -64,6 +64,7 @@ var fishbowls = [...]fishbowlInfo{ Title: "Code skimmability as the root cause for bad code structure decisions", // real snappy, this one Description: `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?`, Month: time.January, Year: 2021, + ContentsPath: "skimming/skimming.html", }, { Slug: "config",