Code Readability and Maintainability


“Don't ask permission to refactor, test, document etc. It's all part of ‘programming’. Don't ask permission to do your job.”

"Fix what isn’t broken. You should go to your last project and read through the code. Think about what each piece does. There's a loop here, some sorting there, a bit of number crunching, screen updates, HTML generation, database CRUD, that sort of thing. Now replace the hard-coded HTML with a templating system, get the database CRUD out of your business objects and re-write it to use proper parameterized queries instead of string concatenation, replace all the "writelns" and "MessageBoxes" in your error handlers with a logging framework, refactor code that's trying to borrow methods from other classes, use locale-aware string formatting, stop guessing how big an array should be and use a dynamic collection, delete orphaned code."

Most developers have heard the saying, "Always write code as if the person who ends up maintaining it will be a violent psychopath who knows where you live." What that means realistically is that you should write readable code that could be easily comprehended a year later by someone who’s disinterested and in a hurry. If you’ve ever had to dig through indecipherable code, you know why this is so important. Have some empathy for the developers who will read your code.

Name variables so that other developers can understand your code better. This is a skill you need to nurture.

Using inheritance often reduces testability and reusability of your object-oriented code in the long run. Your first choice should be using composition and interfaces.

Don’t use design patterns like a hammer looking for a nail. If you don’t have a clear reason you need it, don’t use it.

Always favor shallow code hierarchies to deep-nested code (whether it’s inside or outside a function). Deep-nested code is harder to maintain, harder to reuse, and more likely to create bugs.

Reusable code is helpful and important, but trying to write overgeneralized, super flexible code is often a waste of time. This kind of code is usually harder to maintain and causes bugs. It’s okay to hardcode some things if your code is doing one task.

Master the art of debugging using "print statements." There are many scenarios where a sophisticated debugger is not available to you, but I've never found a platform nor environment where you couldn't output textual information to a screen or file.

Having great writing and communication skills directly translates into programming capability. Joel Spolsky can elaborate on why this is: "The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it's not whether they prefer Python or Java. It's whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless."

Please leave your message and contact
details in the form below