{"id":722,"date":"2024-01-25T14:17:00","date_gmt":"2024-01-25T14:17:00","guid":{"rendered":"https:\/\/blog.67bricks.com\/?p=722"},"modified":"2024-01-25T14:18:01","modified_gmt":"2024-01-25T14:18:01","slug":"coding-principles-2-favour-readability","status":"publish","type":"post","link":"https:\/\/blog.67bricks.com\/?p=722","title":{"rendered":"Coding principles 2: Prioritise readability"},"content":{"rendered":"\n<p>This is the 2nd part of a series about 67 Bricks&#8217;s coding principles. The first post, containing the introduction and first principle is <a href=\"https:\/\/blog.67bricks.com\/?p=710\">here<\/a>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">The principle<\/h2>\n\n\n\n<blockquote class=\"wp-block-quote is-layout-flow wp-block-quote-is-layout-flow\"><p>Aim for clear, readable code. Write clear, readable comments where necessary<\/p><\/blockquote>\n\n\n\n<p>You should make it a priority that your work be readable and understandable to those who might come to it after you. This means you should aim to write code that is as clear and unambiguous as possible. You should do this by:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li>using clear variable, function and class names<\/li><li>avoiding confusing, ambiguous or unnecessarily complicated logic<\/li><li>adhering to the conventions and idioms of the language or technology you\u2019re using<\/li><\/ul>\n\n\n\n<p>What can\u2019t be made clear through code alone should be explained in comments.<\/p>\n\n\n\n<p>Comments should focus on \u201cwhy\u201d (or \u201cwhy not\u201d explanations) far more than \u201chow\u201d explanations. This is particularly true if there is some historical context to a coding decision that might not be clear to someone maintaining the code in the future.<\/p>\n\n\n\n<p>Note however that just like code, comments must be maintained and can become stale or misleading if they don&#8217;t evolve with the code, so use them carefully and only where they add value.<\/p>\n\n\n\n<p>It is important to recognise that your code will be read far more times that it is written, and it will be maintained by people who don\u2019t know everything you knew when you wrote it; possibly including your future self. Aim to be kind to your future self and others by writing code that conveys as much information and relevant context as possible.<\/p>\n\n\n\n<p>I expect we&#8217;ve all had the experience of coming to a piece of code and struggling to understand it, only to realise it was you who wrote it a few months or weeks (or even days?) ago. We should learn from this occasional experience and aim to identify what we could have changed about the code the first time that would have prevented it. Better variable names? More comments? More comprehensive tests?<\/p>\n\n\n\n<p>&#8220;You&#8217;re not going to run out of ink,&#8221; is something a colleague once commented on a pull request of mine to say that I could clarify the purpose of a variable by giving it a longer, more descriptive name. I think that&#8217;s a point worth remembering. Use as many characters as you need to make the job of the next person easier.<\/p>\n\n\n\n<p>Of course, there&#8217;s some subjectivity here. What you see as obscure, someone else might see as entirely clear and vice versa. And certainly there&#8217;s an element of experience in how easily one can read and understand any code. The point really is to make sure that at least a thought is spared for the person who comes to the code next.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Examples<\/h2>\n\n\n\n<p>Here is an example that does not follow this principle:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code class=\"\">const a = getArticles('2020-01-01');\na &amp;&amp; process(a);<\/code><\/pre>\n\n\n\n<p>This example is unclear because it uses meaningless variable names and somewhat ambiguous method names. For example, it&#8217;s not clear without reading further into each method what they do &#8211; what does the date string parameter mean in <code>getArticles<\/code>? It also uses a technique for conditionally executing a method that is likely to confuse someone trying to scan this code quickly.<\/p>\n\n\n\n<p>Now, here&#8217;s an example attempts to follow the principle:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code class=\"\">\/\/ The client is only interested in articles published after 1st Jan\n\/\/ 2020. Older articles are managed by a different system.\n\/\/ See &lt;ticket number>\nconst minDate = '2020-01-01';\n\nconst articlesResult = getArticlesSince(minDate);\nif (articlesResult) {\n  ingestArticles(articlesResult);\n}<\/code><\/pre>\n\n\n\n<p>It provides a comment to explain the \u201cwhy\u201d of the hardcoded date, including relevant context; it uses much more meaningful names for variables and functions; and it uses a more standard, idiomatic pattern for conditionally executing a method.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Resources<\/h2>\n\n\n\n<p><a href=\"https:\/\/www.youtube.com\/watch?v=MBRoCdtZOYg\">Naming is Hard: Let&#8217;s Do Better (Kate Gregory, YouTube)<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>This is the 2nd part of a series about 67 Bricks&#8217;s coding principles. The first post, containing the introduction and first principle is here. The principle Aim for clear, readable code. Write clear, readable comments where necessary You should make it a priority that your work be readable and understandable to those who might come &hellip; <a href=\"https:\/\/blog.67bricks.com\/?p=722\" class=\"more-link\">Continue reading<span class=\"screen-reader-text\"> &#8220;Coding principles 2: Prioritise readability&#8221;<\/span><\/a><\/p>\n","protected":false},"author":11,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[13],"tags":[],"class_list":["post-722","post","type-post","status-publish","format-standard","hentry","category-software-development"],"_links":{"self":[{"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=\/wp\/v2\/posts\/722","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=\/wp\/v2\/users\/11"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=722"}],"version-history":[{"count":7,"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=\/wp\/v2\/posts\/722\/revisions"}],"predecessor-version":[{"id":729,"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=\/wp\/v2\/posts\/722\/revisions\/729"}],"wp:attachment":[{"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=722"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=722"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.67bricks.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=722"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}