Ten Tips for Writing Clean Code

Bill Spooner reports:

"If you’ve ever worked on a development team, or even looked back at some of your old code, there’s probably a chance you came across a certain block of code that looked like someone had a fight on a keyboard while the text editor was open. Messy syntax, unclear variable definitions, and jumbled, cramped code can be a pain to read through — not to mention a nightmare when you’re pushing deadlines and are tasked with sorting through someone else’s sloppy code. So spending some time and learning to keep your code neat, concise, and easy to read is well worth it. Sometimes it can just flow as you’re coding and thinking at the same time, but nothing stops you from going back and cleaning it up once the code works. With a bit of practice, writing clean code will come naturally (and your coworkers will thank you for it)...Using a naming convention is a great way to get started — it keeps things clear and lets you know exactly what you’re working with. It also means you won’t accidentally try to use a string of text in a math equation. A naming convention basically means you decide you’ll call your variables by names that adhere to a certain set of rules...[T]o keep it simple, just make it as clear as possible what type of variable it is, and keep naming consistent...The next thing, which follows nicely from using naming conventions, is using a convention to indicate variable scope. Again, there are no rules, and everyone has their own way of doing it — as long as it’s consistent throughout all of your code, it will always be clear what can be used from where...[T]he most important thing is to have a clear and consistent style. If someone else is looking at your code, they shouldn’t be caught by things not being as they expected...Easily the most frustrating thing for another developer looking at your code is seeing a variable with a misleading name or, worse, named with a single letter. The names you give your variables and functions are incredibly important — it should leave the reader with absolutely no doubt what the variable is used for or what the function does...Using whitespace can be incredibly powerful and normally has absolutely no downside. Sometimes in languages like JavaScript where the file size of the source code itself is important, you might want your files to be small, and that whitespace can add a few extra kilobytes. For the most part, this won’t be too much of a problem, but in the cases where this is important, I would still suggest keeping all your whitespace during development so the code is readable. Then, use one of the many smart little programs that go through code and chop out all the whitespace just before you upload it. So, in general, if you’re writing lots of things together in one block, and then try to separate the code chunks into logical pieces, maybe have all of your code that positions some text fields, then a line of whitespace, and then write another chunk where you assign them all a value. Things like this might seem annoying at the time of writing, but are crucial when trying to quickly find something in a large section of unfamiliar code...Adding comments to your code can be invaluable — they can quickly show what a complex function is doing, or maybe even explain why certain things need to happen in a certain order. They do have a downside, though, because too much commenting can have the opposite effect and actually make for messier code...Comments should be used only when they are needed to describe functionality, or perhaps to remind other programmers of information they otherwise would not have access to at that point...Writing slightly more technical code doesn’t mean it has to be less readable. Lines and lines of duplicate code are not only harder to read than a concise and elegant solution, but also increase the chance for error. The great thing about programming is that you can express complex commands in tidy, reusable, and clever ways...When you have a code block with multiple loops one after the other, you need different iterator variables. There is always debate about what to use, and the answer is slightly subjective, but when they’re one after another, it makes sense to declare your iterator outside of the loop and reuse it. It’s not only better to look at, as it’s always clear that 'i' is your iterator variable, but it’s also slightly more efficient...When your projects start to get larger, your classes will likely have many variables. First, you should be keeping all of your variable declarations at the top of the page, or at the very least all together somewhere — this speeds up any kind of searching when you need to find something. Second[ly], even though they are all together, it often helps to arrange them in such a way that makes them even easier to comprehend...Mile-long function definitions are an easy way to clutter your code. Normally it’s best to take a look at what’s actually being done. If a function is doing more than its name suggests, then perhaps some of the excess functionality could be split out into its own function. This can often help the rest of your code, too, because it becomes easier to look at. And if smaller functional chunks can be used on their own, then it means other parts of your code can use them without the need to duplicate code...Similar to the functional problem, if there’s a large amount of functionality you’re keeping all in one place, it could be better to create a separate class just to handle that functionality. Again, this is all about reusability and keeping your programming tidy — maybe some other classes are using the same functionality, so wouldn’t it be better if, instead, they all accessed a single place that was handling all of these things?...These are just a few different ways to clean up your code — they’re not concrete rules and, of course, you’ll find your own style and way of doing things. Just remember to keep it tidy, clearly sectioned, and consistent. Anyone working with your code will appreciate the effort, and might even learn something from your example."