Is there any way to gauge your own code and evaluate its quality?
Foreword: few people has this sort of ability described below:
Pretend you've never seen your code; pretend you don't know anything about your code and/or the business domain and/or assumptions your code supposes. Then go thru your code and try to figure out if you can understand it given your previous knowledge about it (i.e.: zero knowledgge).
In my experience writing readable and maintainable code is like trying to tell a story to a 10 year old.
Whenever you really have to deviate from those rules, comment. Not only on what you are doing but specially why you are doing it.
Young programmers have a hard time following those. Juniors can't recognize when they are making a mess, but more experienced devs because they like pumping their ego showing the world how smart they are with convoluted code.
I find a great exercise for polishing code is to look at your code and try to explain/interpret what it does to somebody who doesn't know how to read it. Often you'll recognize things like the logical order things should be in, or better names for things based on how you verbalize it to another person that don't occur when you are writing it.
Another idea is to sit down and try to re-write the same code from scratch (without peeking at past solutions) 5+ times. By the time you've rewritten a piece of code many times you have a much better idea what's truly required, and what can be left out!
I'm joining a bit late and I see some wonderful answers already, but let me share how I understand what readable and maintainable code is.
The terms readable and maintainable go hand in hand, although they may be seen as two distinct parts. We all, as developers strive to write understandable and easily extendable code and most of the time we fail, at least on the first try.
"Why?", you might ask. Because writing readable and maintainable code can be hard. In a team, factors like deadlines, unestablished code styles and even value conflicts can be the cause of hardly readable and unmaintainable code.
When we speak about our own code though, things can be a bit different. First of all, you need to know what is wrong with your code to be able to identify bottlenecks and evaluate the readability and maintainability. I try to follow a few principles while coding:
If you are any good at writing code, trust me... you know if your code is good.
There is also objective measure of code complexity, known as cyclomatic complexity. Cyclomatic complexity won't apply to the more aesthetic parts of writing readable code, but it will address the cognitive part.
Cyclomatic complexity is a measure of the number of control flow paths that a piece of code has. Minimizing cyclomatic complexity will make your program more comprehensible. In layman's terms, this essentially equates to minimizing the number of branching statements, breaking large functions into smaller functions and large systems into smaller modules.
There are automated tools for calculating cyclomatic complexity but generally these are only available for enterprise languages or in commercial suites.
Beyond the obvious options...
...it's really hard to say if your own code is "readable" or "maintainable".
The more code you expose yourself to, the more you'll be able to look at it from a distance and judge it's competency. You'll notice patterns, or "smells", that make the code less maintainable or readable (like callback hells or poorly formatted ES6).
If you're forced to search for questions that can't be answered by your documentation, you're not there yet.
There are best practices you can adopt to ensure your code is well documented and formatted correctly. From the code base comments, to the commits, to the docs -- it should be easy to pick up any part of your application and know how to use it.
Go back to your code in 6 months and add a significant feature. Was it a piece of cake? Did you break pre-existing features? What's your code coverage before and after the change? Was the online doc easy to update? Do you need to update Wikis or are they auto-populated with examples. How long will it take to have a stranger add a feature or fix a bug?
When you come back to it 3 months later, how easily can you remember what it does? How easily can you change it to add a new feature? If there's a bug, how easy (or difficult) is it to navigate the code, figure out what's causing the bug, and fixing it?
Use others. Trying to determine if your own code is readable & maintainable or not is inherently a bad idea. It's in fact paradoxical because if you could do that initially, you wouldn't even be asking this. I'm sure most of the people on here know how mean and critical people online and especially on StackOverflow can be.
Use this to your advantage. Write some sample code in the same style of your regular coding (unless you can share the source) and post it on codereview.stackexchange.com or here at Hashnode.
People will probably slam and critique your code and while you may not agree with everything they say, you will get some take-aways and learn things. Keep doing this over and over.
I'll elaborate a bit on how to handle critiques: Someone may show you a more clear and performant want to do something... This is probably good. But if someone slams you for using tabs rather than spaces, or something trivial like your comment style, then you can evaluate yourself whether or not the feedback should be implemented or just noted.
This is also assuming you don't have direct access to reputable coders for review in person. Do both.
Imho, One comes with the other. Easy to read code is easy to maintain and on the opposite side likewise. If I don’t grasp what the code is doing then it’s hard to fix and maintain it.
I follow a simple rule: if I can read and understand the code without any comments then goal achieved.
Doesn’t mean to don’t comment on code. Comment as much as it should be.
Dissecting the question, we have two operative terms here: "readable" and "maintainable."
Let's talk about what these mean.
"Readable" would describe code that is understood without much inspection or explanation by another developer. You have to choose what parameters you want to describe the "other developer" to know what would be readable to them.
Some things are somewhat universal and limited by human factors. For example, few people can follow poorly named variables. (There's your first heuristic - are there clear names for variables, classes, methods, and other references?)
Other things are a bit more nuanced. For example, if the developer uses the language you are writing in on a regular basis.
Or, is the developer familiar with the domain the project operates within? How experienced are they as a developer? Do they have a particular background that might make the code more or less readable to them?
But what if you don't know who the other developer is?
This is why we develop standards, patterns, and best practices. For example, JavaScript code tends to use camelCase, so writing your code with camelCase provides a sense of fluidity (which plays into readability). Knowing the common patterns and style that the language typically uses is important. (As an additional note, your organization may have your own style defined; follow it.)
Some simple, practical heuristics to follow:
All-in-all, coding is a human process. Follow Hemingway's advice when writing code. Simpler is typically better.
I just read this tweet from Mitchell Hashimoto (founder Hashicorp, that you may know for Vagrant, Terraform, Consul, Vault, Packer, Nomad,....)
My heuristic for overly clever or terse code: will another team member (new or not) reading this file top-to-bottom pause here? Is there a way to write it so they don’t? (Sometimes complexity is unavoidable!) If the answer is “yes”, do it, future maintainer will thank you.
It resonates with me, as it sometimes I've been trying to do more and more other the years, but never thought about it more like that.. kind of a habit, almost subconscious. He made me realize that, and that's a simple but super effective way to do it. It will go over all the common problems that make code hard to maintain: naming, splitting functions which are too long, reducing the number of variables, ordering things (all related to the cognitive load), and so on and so forth. A very easy but super effective way to get started!
Leave it for a month, come back to it. If you don't question why you did anything then it's probably ok (or you've got a really good memory). Just follow best practises and you'll be fine :).
Software Security TechLead
Jonathan cartwright
I kinda know based on if my code is really long, undocumented, or has poorly named identifiers. I also know when other people look at it for pull requests for me. If it doesn't make sense to someone else on my project without a ton of explanation, then it's probably not readable or maintainable