4 ms·

Not sure in which context these tips were written. Having been through all of this, and frequently comparing my code-reading abilities with those of my junior c

Not sure in which context these tips were written. Having been through all of this, and frequently comparing my code-reading abilities with those of my junior colleagues (hey, I even managed to make it to a point where I essentially make my living from reading other's code), maybe a few more-realistic tips (and a shorter list): 1. actually read the bloody code until you understand well what it does. Don't stop before that, or it won't count. 2. read as many different projects as you can -- different languages, technologies, paradigms, coding styles. 3. Don't spend time on code-comprehension tools, it won't work (speaking from personal experience. The latest was with "Understand C++" from SciTools, a great tool BTW). Master grep. 4. Drawing flowcharts, running under debugger, etc -- all that would be great but nobody allots time for that anymore (neither yourself nor your managers). 5. Don't hope for usable doc for external libraries. Exceptions exist, but it won't be a rule.

drvdevd 10y ago
I'm interested in your take on #4: why wouldn't you allot time to run code in a debugger? Personally I would like all my code to be written against a debugger and with test suites allowing me to step through it. I've been chided for not doing this in the past (I just read the code usually) and would actually agree with that person in retrospect.
- minipci1321 10y ago
  Because, in many cases, getting it into the debugger has a huge fixed cost -- imagine your code should run on an embedded platform: find the right board, get it connected it into the infrastructure (getting right signals in and out), get the debug build of the image etc -- you see the point. More generally, studying the code under debugger means you need particular input data -- the one suitable for the part of the code you study. That can take time to get.
  - drvdevd 10y ago
    Ah I see. This is actually a very good point. One team I was on would constantly get hung up on this sort of issue. I believe a more general ability to just run a code review and study session would've saved lots of time.
    - softawre 10y ago
      But... if you don't test the code with actual reasonable data, how do you know it is correct? Seems weird to say a team was always hung up on ensuring the correctness of their code. I guess it depends on what you work on to an extent.
      - drvdevd 10y ago
        Well, if the data you're ingesting/parsing/etc is anywhere near well formed or having a known structural definition, you should be able to mock the code handling it reasonably well, even up to the point of covering many weird edge cases. And even with perfect data up front, you would still encounter bugs in your production code at some point. In fact, isn't this usually the case with any application not yet in production? As an example, I had a teammate who would get blocked on needing JSON that matched a production set of data. Yet, she knew what the various fields of the data would most likely contain. She ended up writing the code anyway without the "production" data she asked for and it worked great minus a few small changes. It was ultimately just psychological block, IMO.
  - morbidhawk 10y ago
    You've made some really good points about reading code in both of your posts. I'm fairly new to it, but I've started a daily habit of reading code everyday and I've realized this is an important skill I've omitted in the past. Since most of the code I read (C# code) can be ran on my platform, I'll sometimes run into that rare piece of code that I can't believe it does what it says it does, in those cases I'll download the repo and debug it and many times be surprised to find there was a gap in my understanding. Reading code helps me find knowledge gaps I didn't even know were there.
- JustSomeNobody 10y ago
  For me, if I have to go through "layers of abstraction hell" to get to the point I want the debugger to be in, I'm better off with pencil and paper. This is especial true with enterprise software.
Lewton 10y ago
1 always gets me. My brain will tune out whatever piece of code I've already read once. So if I initially skim some piece of code, figuring out what it -really- does is HARD. Every subsequent look at that piece of code will be colored by my initial (mis)understanding of how it works
- Insanity 10y ago
  Same here, when I am looking for something and I know the area I will read the method or whatever it is rather quickly and be like "oh okay, this is what it does so the problem is not here". Then after some time when I look at it again, I notice that actually I missed a step in that method which actually did contain the problem, which I did not see by skimming over the piece of code earlier.
- thenobsta 10y ago
  Try reading it backwards. It forces your brain to look at the be text differently. This trick is also useful proofreading documents you've read many times already.
dom0 10y ago
3.) -> While newer grep versions and SSDs helped with performance, using ag or any of it's many implementations tends to get results faster, especially on large code bases. 4.) I only had to resort to flow charts a couple times so far, mostly with Java libraries to externalize the data and control flow, because it grew just waaayy to large to keep in my head. A particular vivid memory I have here is netty (which also has a tendency for a particularly convoluted and complex control flow realized through modifying pipelines conditionally in many places).
- pavel_lishin 10y ago
  > using ag or any of it's many implementations tends to get results faster, especially on large code bases. Especially because ag tends to be smart about what it will ignore (e.g., the contents of node_modules, etc.)
  - dom0 10y ago
    ag is also multi-threaded, while recursive GNU grep doesn't do that (you'd need find+xargs workaround).
- rjeli 10y ago
  I like ripgrep, it's instantaneous on our large (>100k loc) codebase

drvdevd 10y ago

I'm interested in your take on #4: why wouldn't you allot time to run code in a debugger? Personally I would like all my code to be written against a debugger and with test suites allowing me to step through it. I've been chided for not doing this in the past (I just read the code usually) and would actually agree with that person in retrospect.

minipci1321 10y ago
Because, in many cases, getting it into the debugger has a huge fixed cost -- imagine your code should run on an embedded platform: find the right board, get it connected it into the infrastructure (getting right signals in and out), get the debug build of the image etc -- you see the point. More generally, studying the code under debugger means you need particular input data -- the one suitable for the part of the code you study. That can take time to get.
- drvdevd 10y ago
  Ah I see. This is actually a very good point. One team I was on would constantly get hung up on this sort of issue. I believe a more general ability to just run a code review and study session would've saved lots of time.
  - softawre 10y ago
    But... if you don't test the code with actual reasonable data, how do you know it is correct? Seems weird to say a team was always hung up on ensuring the correctness of their code. I guess it depends on what you work on to an extent.
    - drvdevd 10y ago
      Well, if the data you're ingesting/parsing/etc is anywhere near well formed or having a known structural definition, you should be able to mock the code handling it reasonably well, even up to the point of covering many weird edge cases. And even with perfect data up front, you would still encounter bugs in your production code at some point. In fact, isn't this usually the case with any application not yet in production? As an example, I had a teammate who would get blocked on needing JSON that matched a production set of data. Yet, she knew what the various fields of the data would most likely contain. She ended up writing the code anyway without the "production" data she asked for and it worked great minus a few small changes. It was ultimately just psychological block, IMO.
- morbidhawk 10y ago
  You've made some really good points about reading code in both of your posts. I'm fairly new to it, but I've started a daily habit of reading code everyday and I've realized this is an important skill I've omitted in the past. Since most of the code I read (C# code) can be ran on my platform, I'll sometimes run into that rare piece of code that I can't believe it does what it says it does, in those cases I'll download the repo and debug it and many times be surprised to find there was a gap in my understanding. Reading code helps me find knowledge gaps I didn't even know were there.
JustSomeNobody 10y ago
For me, if I have to go through "layers of abstraction hell" to get to the point I want the debugger to be in, I'm better off with pencil and paper. This is especial true with enterprise software.

Lewton 10y ago

1 always gets me. My brain will tune out whatever piece of code I've already read once. So if I initially skim some piece of code, figuring out what it -really- does is HARD. Every subsequent look at that piece of code will be colored by my initial (mis)understanding of how it works

Insanity 10y ago
Same here, when I am looking for something and I know the area I will read the method or whatever it is rather quickly and be like "oh okay, this is what it does so the problem is not here". Then after some time when I look at it again, I notice that actually I missed a step in that method which actually did contain the problem, which I did not see by skimming over the piece of code earlier.
thenobsta 10y ago
Try reading it backwards. It forces your brain to look at the be text differently. This trick is also useful proofreading documents you've read many times already.

dom0 10y ago

3.) -> While newer grep versions and SSDs helped with performance, using ag or any of it's many implementations tends to get results faster, especially on large code bases. 4.) I only had to resort to flow charts a couple times so far, mostly with Java libraries to externalize the data and control flow, because it grew just waaayy to large to keep in my head. A particular vivid memory I have here is netty (which also has a tendency for a particularly convoluted and complex control flow realized through modifying pipelines conditionally in many places).

pavel_lishin 10y ago
> using ag or any of it's many implementations tends to get results faster, especially on large code bases. Especially because ag tends to be smart about what it will ignore (e.g., the contents of node_modules, etc.)
- dom0 10y ago
  ag is also multi-threaded, while recursive GNU grep doesn't do that (you'd need find+xargs workaround).
rjeli 10y ago
I like ripgrep, it's instantaneous on our large (>100k loc) codebase