• Readability: Avoid comments

    One of the best things you can do to improve the readability of your code is to avoid comments. "Uh, what?" — I hear you say — "That goes against all good coding guidelines, which state to heavily comment your code!" [Continue reading]

  • Readability: Document your types

    Wow. The previous post titled Self-interview after leaving the NetBSD board has turned out to be, by far, the most popular article in this blog. The feedback so far has been positive and I owe all of you a follow-up post. However, writing such post will take a while and content must keep flowing. So let's get back to the readability series for now. [Continue reading]

  • Self-interview after leaving the NetBSD board

    The decision to not renew my NetBSD board membership was bittersweet. [Continue reading]

  • Readability: Mind your typos and grammar

    I can't claim to be an expert writer — not in English, and not even in my native languages — but I do put a lot of attention to whatever I write: emails, presentations, letters and, of course, code. As it turns out, code has prose in it most of the time in the form of comments and documentation. [Continue reading]

  • Lutok 0.3 released

    Lutok 0.3 was released yesterday evening. The packages in pkgsrc-current, Fedora 19 and Fedora rawhide have all been updated accordingly. [Continue reading]

  • Readability: No abbreviations

    When you are writing code, it is very tempting to shorten the names of functions and variables when the shortening seems blatantly obvious. All of us have, at some point, written calc_usage instead of calculate_usage; res instead of result; stmt instead of statement; ctx instead of context; etc. The thought goes "well, these abbreviations are obvious, and I'll be a much faster developer!" Wrong. You might think you are faster at typing, but you don't write code in one go and never ever get back to it again. As we have already mentioned, code is usually only written once and is later read many times, possibly by people other than the original developer. At the very least, I'd expect you going over your code once before checking it into your repository. Spending the extra minute it takes to write words in full will benefit you and your readers. [Continue reading]

  • Readability: Blank lines matter

    Vertical spacing is important for readability reasons: group together pieces of code that should not be split apart, and otherwise add blank lines among chunks of code that could be easily reordered and/or repurposed. That's a pretty loose suggestion though, so let's look at some specific situations in which you want to consider your vertical spacing practices (both adding and removing). [Continue reading]

  • Readability: Blocks and variable scoping

    In a dynamically-typed language, it is common for the scoping semantics of a variable to be wider than a single code block. For example: in at least Python and the shell, it is the case that a variable defined anywhere within a function —even inside conditionals or loops— is reachable anywhere in the function from there on. [Continue reading]

  • Readability: Series introduction

    Dear readers, [Continue reading]