Code quality is a critical aspect of software development, encompassing various practices and principles aimed at producing clean, maintainable, and efficient code. It involves structuring code for readability, eliminating redundancy through reusable components, documenting with comments, conducting thorough unit testing, and selecting appropriate development tools. Ensuring high code quality not only enhances the long-term maintainability and reliability of software but also leads to more efficient development processes and fewer errors, ultimately resulting in a superior user experience and a more successful project.
File Structure:
Folder structure, as much as possible make sure that your files are organized, do search the internet on how to structure your folder properly. This is important for maintainability because it's easier for developers to find, understand, and modify specific parts of the codebase. This reduces the time and effort required for making changes and debugging issues.
Reusable Codes
Make sure that if a function can be used elsewhere, make it a separate function. In short, be sure to create reusable methods/code. We don't want to bulk our code with too many duplicate codes. So, make sure to think about this one especially if you're refactoring your codes.
Comments
These comments are very important. Comments will not affect your codes; they will not affect the performance. These are like your code's personal tour guide, making your programming easier to grasp and more enjoyable for everyone involved. They offer insights into the purpose and inner workings of your code, ensuring that it's not just a bunch of cryptic symbols to decipher. Comments are also handy notes to your future self or your team, helping you avoid confusion, catch mistakes, and plan for future enhancements. So, think of comments as your friendly companions in the world of programming, guiding you through the coding journey with clarity and camaraderie.
NOTE: Write Good comments not bad comments. Bad comments are comments that are written everywhere that don't need to be written.
example:
// GOOD Comment
/**
* Get a list of inactive services and extensions on an account for a given threshold period
*
* @param AccountCustomerMap $account The account we want to interrogate
* @param string $period the strtotime period for the inactive threshold
* @return array an array containing either the phone number or extension reg name
*/
public static function inactiveItemsOnAccount(AccountCustomerMap $account, string $period = '-6 months'): array
{
// long methods of codes
}
// BAD COMMENTS
/**
* This function will investigate the customer. -> this does not make sense. Give a little more description because the function name already has this explaniation.
*/
function investigateCustomer($customerID) {
// get customer -> this comment should not be here, its its obviouse the code is getting the customer
$customer = Customer::get($customerID);
// ... methods
}
"It's better to reserve code comments for cases where you need to explain specific business logic/rules. At function level you should almost never need a comment, because the name and parameters should be descriptive enough themselves. If it needs further comments, its often a sign that the function needs a better name, or is trying to do too many things and should be split into smaller functions." taken from the comments bellow
Unit Tests
As much as possible especially if the project is just in its early stage, create tests because it's going to help in the long run. I promise. This also will be going to make the quality of the methods better. But if the project is not new, start creating tests for important functions, and test the minor functions later. I also suggest using typescript for type safety.
I advise that you find the test framework for the programming language your using, here are some of my suggestions.
JavaScript Popular tools for testing: Mocha, Jasmine, Unit JS, Jest
PHP popular tools for testing: PHPUnit
Other Suggestions: Vitest | Next Generation testing framework.
IDE is also important
If you are using VS Code, make sure to install the necessary extensions for development, and use the VS Code profile system so that you can set specific profiles for each dev environment.
For Me I recommend using the JetBrains product, the reason is you will have full support on the specific dev language you are using ex. PHPStorm for PHP development, WebStorm for web development, PyCharm for Python development, etc. It has features, that will definitely be going to help like refactoring, code duplicate checker, etc. If you have an Open-Source Project, you can apply for a free license here: Licenses for Open-Source Development (jetbrains.com)
AI Tools
Maximize your use of AI to streamline various tasks. Traditional search engines like Google Search are becoming less effective for code-related queries, while AI-powered options such as Chat GPT, Bard, and Edge Copilot by Microsoft Edge have emerged as the leading choices.
I hope this post helped you. Cheers š» and have a nice day š
Are you ready to be successful in Life? "The Power of Positive Thinking: A Guide to Transforming Your Life" is your roadmap to achieving lasting happiness, success, and personal growth through the incredible power of positive thinking.
Get the eBook here now: The Power of Positive Thinking: A Guide to Transforming Your Life (store.brojenuel.com)
Top comments (15)
Nice article, good to see AI as well. I would add code linting tools as well, that helps to maintain readability and consistency.
Iām kind of disagreeing with comments. They are optional and can be on top of everything else. We need to keep them up to code all the time, otherwise they are dangerous
agree, I don't like comments either but as I said, comments are like tour guides. This will help other new developers, especially the new Devs coming in. And it can also work like a note, so that if you come back to the code after a long time, at least you know what is for. Comments are really good, and it also gives linting for your IDE:
Just updated the comment section now for example.
That comment is proving the case for no or minimal commenting. If a getInactiveItemsOnAccount method, notice the prefix, did anything but what it says there are bigger issues at play.
Sorry for the context, here is a context:
"The function is quite old and is being used in different places. With old developers out, and with new developers on board, we felt it was important to add comments to make things clearer for everyone. š"
Good write up, just wouldn't entirely agree on comments part, it depends, but if you can make your code clear enough that it doesn't need comments, the better.
I agree with writing super readable code so that others can easily understand it, but I still think writing good comments are helpful. I want to make sure that whoever is looking through my code can quickly understand what they are looking at and then intentions behind. Sometimes, over communication isn't a bad thing in my opinion.
As long as the comment is maintained its fine, keep in mind that comments also need to be maintained when code changes, and nothing actually enforces the comment to be true, so it might be lying
So I would recommend to use them sparingly, when something really needs an explanation, for other stuff tests can be documentation
Agree It depends. I don't like comments either but as I said, comments are like tour guides. This will help other new developers, especially the new Devs coming in. And it can also work like a note, so that if you come back to the code after a long time, at least you know what is for. Comments are really good, and it also gives linting for your IDE:
Just updated the comment section now for example.
If you can properly type your methods (depends on the language), you shouldn't need those nasty @param @return comments, as they are already defined in the code, unless you're actually "typing" the code with comments :/
Yup, totally agree with you. It's true that well-typed code can reduce the need for comments in many cases. And, comments still play an essential role in programming for several reasons which can be for clarification, documentation, API library usage, maintainability, and collaboration.
It's better to reserve code comments for cases where you need to explain specific business logic/rules. At function level you should almost never need a comment, because the name and parameters should be descriptive enough themselves. If it needs further comments, its often a sign that the function needs a better name, or is trying to do too many things and should be split into smaller functions.
agree, Im going to put this above
I agree with the comment, this really important for all developer
practice, practice and practice. Build some good projects.