Skip to content

Instantly share code, notes, and snippets.

@lkuper
Created December 29, 2017 03:48
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save lkuper/709bd9235f4eb71f007536fa1fecb0a8 to your computer and use it in GitHub Desktop.
Save lkuper/709bd9235f4eb71f007536fa1fecb0a8 to your computer and use it in GitHub Desktop.
Revision history of one of my blog posts.
$ git log -p --word-diff 2015-12-29-refactoring-as-a-way-to-understand-code.markdown | cat
commit 698f4140d1f141b339731f8fe8c984137f93880e
Author: Lindsey Kuper <lindsey@composition.al>
Date: Fri Jun 9 14:00:31 2017 -0700
Tweak a bunch of tags, mostly!
diff --git a/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
index 8cafa552c1..e3ccd2b267 100644
--- a/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
+++ b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
@@ -3,7 +3,7 @@ layout: post
title: "Refactoring as a way to understand code"
date: 2015-12-29 23:29
comments: true
categories: [-[programming]-]{+[refactoring]+}
published: true
---
commit e85dd1d6ee08f306c88bee81e90d4400d9c53dc7
Author: Lindsey Kuper <lindsey@composition.al>
Date: Thu Dec 31 09:26:02 2015 -0800
Wording tweak.
diff --git a/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
index 6b2a605d75..8cafa552c1 100644
--- a/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
+++ b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
@@ -11,7 +11,7 @@ Recently, an acquaintance was complaining of a project they were working on that
<!-- more -->
{+I can sympathize.+} As a researcher, I'm often faced with piles of undocumented, untested, poorly-engineered, "research-quality" code that I need to somehow come to understand well enough to modify. What I've found is that I can't just sit there and read that kind of code for very long; I don't learn anything, and I end up miserable. I need to dig in and start trying to refactor.
The idea is to pick some concrete task and attempt it. Depending on the code, some options (in order of how ambitious they are) might include:
commit 7abd5c24df4a84665eebbaa0c6b411e5a7d8bf1d
Author: Lindsey Kuper <lindsey@composition.al>
Date: Tue Dec 29 21:30:54 2015 -0800
Wording tweak.
diff --git a/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
index e4a62ca5be..6b2a605d75 100644
--- a/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
+++ b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
@@ -24,6 +24,6 @@ When I'm at this stage, I may find that I don't know enough about the code to re
Whatever it is that I learn while traipsing through the code, I can document that knowledge in some way, if only by adding the occasional explanatory comment. And, if there are no tests (which, if it's research code, there often aren't), I can try to write them as I go along. Adding tests not only helps with my understanding of the code, it'll also help me be more confident of the changes I make when I attempt the next round of refactoring.
All this might seem like a strange approach to learning one's way around a project. After all, refactoring is supposed to improve the design of existing code -- how can anyone be expected to *improve* code before they even know what it does? For me, the trick is to realize that at this stage, improving the code isn't the point. Maybe I'll end up making some improvements as a side effect, but even if I don't, refactoring helps *me*. It increases my feeling of ownership over the code, which will help me stay motivated to continue working on it. Most importantly, the act of editing the code myself (if only just to rename things or move them around), rather than passively reading it, will help solidify things about the code in my memory and [-get-]{+give me+} a more visceral sense of what it's doing. That can only be good for my understanding of the code, even if I end up deciding not to keep the changes I made.
_Thanks to Maggie Zhou, Julia Evans, Scott Feeney, Darius Bacon, and Dan Luu for discussing the ideas in this post with me. (None of them are the aforementioned acquaintance!)_
commit 94b6013013509417da77e18f5e5d89ddad1686f5
Author: Lindsey Kuper <lindsey@composition.al>
Date: Tue Dec 29 20:43:02 2015 -0800
New post.
diff --git a/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
new file mode 100644
index 0000000000..e4a62ca5be
--- /dev/null
+++ b/source/_posts/2015-12-29-refactoring-as-a-way-to-understand-code.markdown
@@ -0,0 +1,29 @@
{+---+}
{+layout: post+}
{+title: "Refactoring as a way to understand code"+}
{+date: 2015-12-29 23:29+}
{+comments: true+}
{+categories: [programming]+}
{+published: true+}
{+---+}
{+Recently, an acquaintance was complaining of a project they were working on that involved reading a mountain of "incidentally complex" code -- code that wasn't doing anything particularly interesting algorithmically, but that was nevertheless so hairy that it was difficult to understand the implications of adding even the small feature they wanted to add. After reading code non-stop for a week, they were tearing their hair out in frustration.+}
{+<!-- more -->+}
{+As a researcher, I'm often faced with piles of undocumented, untested, poorly-engineered, "research-quality" code that I need to somehow come to understand well enough to modify. What I've found is that I can't just sit there and read that kind of code for very long; I don't learn anything, and I end up miserable. I need to dig in and start trying to refactor.+}
{+The idea is to pick some concrete task and attempt it. Depending on the code, some options (in order of how ambitious they are) might include:+}
{+ * changing so-called ["magic numbers"](https://en.wikipedia.org/wiki/Magic_number_%28programming%29#Unnamed_numerical_constants) to named constants;+}
{+ * removing dead code;+}
{+ * splitting uncomfortably long functions up into shorter ones; or+}
{+ * factoring repetitive things out into their own functions or interfaces.+}
{+When I'm at this stage, I may find that I don't know enough about the code to really be able to refactor well. But the beauty of attempting to refactor is that even if I'm not able to make an improvement, I can still benefit just from *attempting* the improvement. I can make work-in-progress commits in a branch, and at the end of the day, if I think that my changes are an improvement, I can decide to clean up and keep those commits. If not, that's okay; I still learned *something* about how the code is organized or what it does.+}
{+Whatever it is that I learn while traipsing through the code, I can document that knowledge in some way, if only by adding the occasional explanatory comment. And, if there are no tests (which, if it's research code, there often aren't), I can try to write them as I go along. Adding tests not only helps with my understanding of the code, it'll also help me be more confident of the changes I make when I attempt the next round of refactoring.+}
{+All this might seem like a strange approach to learning one's way around a project. After all, refactoring is supposed to improve the design of existing code -- how can anyone be expected to *improve* code before they even know what it does? For me, the trick is to realize that at this stage, improving the code isn't the point. Maybe I'll end up making some improvements as a side effect, but even if I don't, refactoring helps *me*. It increases my feeling of ownership over the code, which will help me stay motivated to continue working on it. Most importantly, the act of editing the code myself (if only just to rename things or move them around), rather than passively reading it, will help solidify things about the code in my memory and get a more visceral sense of what it's doing. That can only be good for my understanding of the code, even if I end up deciding not to keep the changes I made.+}
{+_Thanks to Maggie Zhou, Julia Evans, Scott Feeney, Darius Bacon, and Dan Luu for discussing the ideas in this post with me. (None of them are the aforementioned acquaintance!)_+}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment