feed.xml

<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" ><generator uri="https://jekyllrb.com/" version="3.8.3">Jekyll</generator><link href="https://edwrites.blog/feed.xml" rel="self" type="application/atom+xml" /><link href="https://edwrites.blog/" rel="alternate" type="text/html" /><updated>2018-09-18T09:01:55-05:00</updated><id>https://edwrites.blog/feed.xml</id><title type="html">Ed writes that blog</title><subtitle>This is Ed's blog about writing and designing software for people not for compilers</subtitle><entry><title type="html">You write code for you not the interpreter (or compiler)</title><link href="https://edwrites.blog/2016/05/10/you-write-code-for-you-not-the-interpreter.html" rel="alternate" type="text/html" title="You write code for you not the interpreter (or compiler)" /><published>2016-05-10T20:07:13-05:00</published><updated>2016-05-10T20:07:13-05:00</updated><id>https://edwrites.blog/2016/05/10/you-write-code-for-you-not-the-interpreter</id><content type="html" xml:base="https://edwrites.blog/2016/05/10/you-write-code-for-you-not-the-interpreter.html">&lt;p&gt;I love software. What I mean by that is that I love writing software. But what I really mean by that is that I love reading and writing software. You see, whenever you write a line of code you have most surely read at least ten, a hundred or even more. You even have to read the line you just typed and make sure it makes sense.&lt;/p&gt;

&lt;p&gt;What I mean to say is that the time you use reading software far outweighs the time you use writing it. I’m by all means that last person to say this.&lt;/p&gt;

&lt;p&gt;Either way, what I usually see from teammates’ code and code tests from developer candidates I review at Grability is that people haven’t internalize the actual implications of that fact. If reading code is what you’re gonna be doing MOST of your time, then you should spend MOST of your writing time making sure that reading it later is as easy and straightforward as it gets. Making code work is only half the job. The easy half for that matter (although it is hard). Making sure it’s easy to read and understand is what takes all of your attention. &lt;strong&gt;Everyday&lt;/strong&gt;. In the good days when you care deeply for your code base and (specially) in the bad days where you just want to get shit done and move on. That &lt;strong&gt;is&lt;/strong&gt; the hard part.&lt;/p&gt;

&lt;p&gt;Everybody seems to take that last part for granted. That you only need to get things to work before moving on. That next time you revisit the code and try to understand it (understanding it will always come before fixing or extending) things will flow naturally. That, as we all know, is not the case. Good news is that both the easy and the hard part of writing code, are not rocket science. We all can do it. So, here I want to share simple rules of thumb I have learnt so far that I think can help you write code that’s easier to understand, as they have helped me and my team:&lt;/p&gt;

&lt;h4 id=&quot;-say-what-you-meannaming-is-hard&quot;&gt;&amp;gt; Say what you mean/&lt;a href=&quot;https://www.sitepoint.com/whats-in-a-name-anti-patterns-to-a-hard-problem/&quot;&gt;naming is hard&lt;/a&gt;:&lt;/h4&gt;
&lt;p&gt;Let’s say you need to create a method that returns the closest stores to your location. Chances are people will name it something like:&lt;/p&gt;

&lt;figure class=&quot;highlight&quot;&gt;&lt;pre&gt;&lt;code class=&quot;language-javascript&quot; data-lang=&quot;javascript&quot;&gt;&lt;span class=&quot;nx&quot;&gt;get_stores&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;location&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;

&lt;p&gt;(don’t believe me? go open a random class in yours or somebody else’s code base, you’ll be lucky to find something better). I think you should instead ask yourself, what does that method do? Well, it returns the closest stores to your location. So, why not use a name that actually describes what it does. Something like:&lt;/p&gt;

&lt;figure class=&quot;highlight&quot;&gt;&lt;pre&gt;&lt;code class=&quot;language-javascript&quot; data-lang=&quot;javascript&quot;&gt;&lt;span class=&quot;nx&quot;&gt;get_closest_stores_to&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;location&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;// or maybe&lt;/span&gt;
&lt;span class=&quot;nx&quot;&gt;get_nearby_stores_for&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;location&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;

&lt;p&gt;A couple of characters to spare won’t hurt anybody. Take the time to make sure the name you choose &lt;em&gt;conveys&lt;/em&gt; what the code is actually doing.&lt;/p&gt;

&lt;h4 id=&quot;-mean-what-you-say-avoid-surprises&quot;&gt;&amp;gt; Mean what you say/ avoid surprises:&lt;/h4&gt;
&lt;p&gt;If you have a &lt;code class=&quot;highlighter-rouge&quot;&gt;get_nearby_stores_for(location)&lt;/code&gt; method, people wouldn’t expect it to run any update on the database or more generally to have any side effect. Take the time to make sure the code you’re adding doesn’t invalidate previous chosen names in a way that people reading the name may be surprised by the contents of the method, or variable or class. For instance, no method that starts with a get should have any side effects.&lt;/p&gt;

&lt;h4 id=&quot;-never-use-boolean-parameters&quot;&gt;&amp;gt; Never use boolean parameters:&lt;/h4&gt;
&lt;p&gt;You’ll never ever ever remember what &lt;code class=&quot;highlighter-rouge&quot;&gt;delete_from(location, false)&lt;/code&gt; does. In contrast, you don’t have to remember what &lt;code class=&quot;highlighter-rouge&quot;&gt;delete_recursively_from(location)&lt;/code&gt; does. It’s right there. This doesn’t mean you have to duplicate code in &lt;code class=&quot;highlighter-rouge&quot;&gt;delete_from&lt;/code&gt; and &lt;code class=&quot;highlighter-rouge&quot;&gt;delete_recursively_from&lt;/code&gt;, you should use boolean parameters if that removes duplication (&lt;a href=&quot;http://verraes.net/2014/08/dry-is-about-knowledge/&quot;&gt;not in code but in knowledge&lt;/a&gt;) but your public method names should be as easy to read as possible.&lt;/p&gt;

&lt;h4 id=&quot;-negated-values-are-harder-to-reason-about&quot;&gt;&amp;gt; Negated values are harder to reason about:&lt;/h4&gt;
&lt;p&gt;I think this is not as relevant in Ruby as it is in most languages, since you can use the amazing &lt;code class=&quot;highlighter-rouge&quot;&gt;unless&lt;/code&gt; syntax, but it’s harder for most people to understand:&lt;/p&gt;

&lt;figure class=&quot;highlight&quot;&gt;&lt;pre&gt;&lt;code class=&quot;language-php&quot; data-lang=&quot;php&quot;&gt;&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;!&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;is_null&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$newHash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
 &lt;span class=&quot;k&quot;&gt;break&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
 &lt;span class=&quot;nv&quot;&gt;$storeIdBlackList&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;$nearbyStore&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;store_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;

&lt;figure class=&quot;highlight&quot;&gt;&lt;pre&gt;&lt;code class=&quot;language-php&quot; data-lang=&quot;php&quot;&gt;&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;is_null&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$newHash&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
 &lt;span class=&quot;nv&quot;&gt;$storeIdBlackList&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;$nearbyStore&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;store_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
 &lt;span class=&quot;k&quot;&gt;break&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;

&lt;p&gt;(This is the actual piece of code that encouraged me to write this post). While we’re at it, try an add a blank space after the !. It makes a HUGE difference as it accentuates it’s presence so it’s way harder to miss it when reading.&lt;/p&gt;

&lt;h4 id=&quot;-be-consistent&quot;&gt;&amp;gt; Be consistent:&lt;/h4&gt;
&lt;p&gt;If you prefix private variables with __ then do it everywhere. If you’re in JS and you don’t want to add a semicolon at the end of each line, don’t add it anywhere. If you name the classes that interact with the DB “Repository”, name all classes with the same purpose “Repository”. Take the time to choose the right name for the thing you’re creating and once you do, stick with it. There are times for creativity and there are times for just being rigorous. This doesn’t mean you have to stick with names you don’t like or are not applicable anymore, it means that if you change the meaning of a concept then that meaning should change all across the specific &lt;a href=&quot;http://verraes.net/2014/02/buzzword-free-bounded-contexts/&quot;&gt;context&lt;/a&gt;, given your application is large enough, or all across your code base, if it isn’t.&lt;/p&gt;

&lt;p&gt;Avoid as much as you can naming things the same way if they behave differently, or differently is they behave in the same manner. Create a vocabulary, a set of concepts for you code base and then just follow it.&lt;/p&gt;

&lt;h4 id=&quot;-give-names-to-code-that-is-not-obvious&quot;&gt;&amp;gt; Give names to code that is not obvious:&lt;/h4&gt;
&lt;p&gt;Most of the times where you’re reading code, you don’t need to understand every specific detail. You need to understand the general picture and then understand some specific parts of the implementation that might be related to what you’re trying to fix or add. This means that while reading you should be able &lt;em&gt;opt-in&lt;/em&gt; to know &lt;strong&gt;how&lt;/strong&gt; some specifics are implemented after you know &lt;strong&gt;what&lt;/strong&gt; the implementation is doing. There’s no need to overwhelm future you with all the details up front. Let’s say you have something like this:&lt;/p&gt;

&lt;figure class=&quot;highlight&quot;&gt;&lt;pre&gt;&lt;code class=&quot;language-php&quot; data-lang=&quot;php&quot;&gt;&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;substr_count&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;err&quot;&gt;‘&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;’&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;.&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;$versionToDelete&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;id&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;.&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;::&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;EXTENSION_SQL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;::&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;MATCHES_VERSIONS_IN_DELTA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nv&quot;&gt;$this&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;delete&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;

&lt;p&gt;At first when you read this code, you don’t need to know &lt;strong&gt;how&lt;/strong&gt; you decide if you need to delete a file. You need to know &lt;strong&gt;that&lt;/strong&gt; (what) depending on something you may delete or not the file. The alternative looks something like this:&lt;/p&gt;

&lt;figure class=&quot;highlight&quot;&gt;&lt;pre&gt;&lt;code class=&quot;language-php&quot; data-lang=&quot;php&quot;&gt;&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$this&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;fileIsDelta&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nv&quot;&gt;$this&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;delete&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;// .....&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;protected&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;fileIsDelta&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;substr_count&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nv&quot;&gt;$file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;err&quot;&gt;‘&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;’&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;.&lt;/span&gt; &lt;span class=&quot;nv&quot;&gt;$versionToDelete&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;id&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;.&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;::&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;EXTENSION_SQL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;::&lt;/span&gt;&lt;span class=&quot;na&quot;&gt;MATCHES_VERSIONS_IN_DELTA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;

&lt;p&gt;This way, if after knowing &lt;strong&gt;what&lt;/strong&gt; is happening you know that you have to change how files are filtered to be deleted then you &lt;em&gt;opt-in&lt;/em&gt; the specifics and read the &lt;em&gt;fileIsDelta&lt;/em&gt; method implementation.&lt;/p&gt;

&lt;h4 id=&quot;-give-a-shit&quot;&gt;&amp;gt; Give a shit:&lt;/h4&gt;
&lt;p&gt;Most of all, we all need to give a shit about how code reads. This, I think, is the most difficult thing to actually do. You have to ask yourself every time you‘re writing code.&lt;/p&gt;
&lt;blockquote&gt;
  &lt;p&gt;Is this self explanatory?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote&gt;
  &lt;p&gt;Is it easy to know what is happening in this piece of code?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote&gt;
  &lt;p&gt;Is it easy to understand the general picture of what’s happening?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote&gt;
  &lt;p&gt;Can people other than me (most surely future me) read this without jumping back and forth between parts of the file or different files?&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Last but not least, I want to stress out that you don’t need to give every line of code 1 hour of reviewing and name choosing. You can’t afford it, you need to get shit done NOW. Likewise, you can’t spend zero seconds reviewing code, being consistent and avoiding surprises. Future you also needs to get shit done. There’s a balance between the two of you, a trade off, and keeping it is the beauty of doing the thing we love to do. Writing code.&lt;/p&gt;

&lt;p&gt;&lt;br /&gt;
&lt;br /&gt;
&lt;br /&gt;&lt;/p&gt;

&lt;hr /&gt;
&lt;p&gt;Most of the things I wrote here came from some of the following resources, they’re amazing, give them a try: &lt;a href=&quot;http://www.poodr.com/&quot;&gt;Practical Object-Oriented Design in Ruby&lt;/a&gt;, &lt;a href=&quot;https://www.youtube.com/watch?v=DC-pQPq0acs&quot;&gt;Refactoring from Good to Great&lt;/a&gt;, &lt;a href=&quot;https://www.youtube.com/watch?v=J4dlF0kcThQ&quot;&gt;Therapeutic Refactoring&lt;/a&gt;, &lt;a href=&quot;https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882&quot;&gt;Clean Code&lt;/a&gt;.&lt;/p&gt;</content><author><name></name></author><category term="software" /><category term="code" /><summary type="html">I love software. What I mean by that is that I love writing software. But what I really mean by that is that I love reading and writing software. You see, whenever you write a line of code you have most surely read at least ten, a hundred or even more. You even have to read the line you just typed and make sure it makes sense.</summary></entry></feed>