Seven Honest Code Writing Techniques

Becca Barton reports:

"Writing code that is clear and upfront about its intention and purpose reduces confusion and headaches for everyone involved, so let’s all pledge to decrypt our code and make it a painless experience...Be upfront. As soon as you know you’re going to be using a variable, declare it. This means putting all of your variables at the top of a function. Think of it as setting up the characters that your story is going to use. You want to give the readers of your code an idea of who the main players of the function are going to be. Of course, all your variables will end up being hoisted up to the top of their scope anyway, but this adds to readability and makes it clear which scope the variable will be available in. It’s also helpful to add a few lines of commenting at the beginning to describe what the program will do. Think of it as a thesis statement for a viewer (or future you) so they know what to expect in the lines to come...How many times have you written something that[,] in theory, should work, but at runtime something unexpected happens? We can’t predict every outside force that is going to act on the program, and this is where testing comes in. Writing tests helps in a couple of ways: [F]irst, by writing them out, you’re forced to be very clear about what your program should be doing, and what you expect the result to be. Second[ly], you can find out pretty quickly if this is what the program is actually doing...Starting out a program by writing tests for it first makes sure your code is staying on track with its purpose, and that you’re always working on functional code. And as an added bonus, you can go forth and refactor confidently knowing that you aren’t breaking your code (or, at the very least, knowing exactly what it was that you did that broke it)...Name your variables for what they are. Name your functions for what they do. Think of your program as a story, and each function as a chapter. Choose the names of variables and functions so that when written, your code flows as closely to a complete sentence as possible. Ideally your functions would flow semantically, and it should be obvious when reading through how each contributes to the program’s narrative...[W]rite for your audience. Keep in mind that a new viewer to your code doesn’t have the full context of the program that you do. Continue to ask yourself as you write what clues you can add to your program to give more context to an outside viewer. Is there a variable that looks out of place because it’s relying on the syntax of a gem? Add some comments to clarify why it’s there. Find ways to keep your audience on your level of understanding...If your intentions for the program or a function change, rewrite your code to reflect this new purpose...Going back to rewrite or delete code that is no longer serving the purpose it needs to as soon as possible helps your program flow, and also helps to ensure that every piece of the program is serving a specific and clear purpose. In other words, if a piece of code is no longer needed, let it go. After writing a program, go back to rearrange the functions in the order that they are called...If you think there’s a chance for confusion in your program, add comments to clarify why a function exists or what exactly it’s doing. Err on the side of over-explaining, and your readers will thank you...[D]on’t be careless. If a variable only needs to be in scope of one function, don’t allow it to become a part of the global namespace. If a function really belongs to a class, make it a prototype, and don’t let it become a global function. Be honest with each part of your program about what it does, what other elements it should be able to interact with, and what other parts have access to it. Keep everything in its rightful place. One place where this really becomes an issue is in the global section of your program. If you’ve got a lot of variables mixing around in the global namespace, and functions that can be called at any time, it’s much easier to run into unexpected issues with conflicting variables. Again, think of it in the context of a novel: It’s much easier (and enjoyable) to follow a novel that handles one plotline at a time between just a few select characters, as opposed to a novel that’s trying to simultaneously juggle multiple plotlines between fifty different characters."