Structurize your code

When you start a new project, before writing any code, first create the most common folders you will be using. This will help you to stay organized.

This can also helps you to keep a clear file structure which in turn will help you to avoid large files. Put every file in the appropriate folder (using names that make it clear what's inside of it) so everyone knows where to find it.

If you have the structure for your project in place, it is so much easier to create separate files in those folders. Thus avoiding doing everything in one large chunk of code in one large file.

So set the standard for your project right from the begining. It makes it so much easier to keep yourself to that standard.

Good naming conventions

First and most important is a good naming convention. Use descriptive naming for your files, variables, functions, classes and everything you write. This will make your code easy to understand for everybody who has to work on it.

Be complete and avoid generic names. If you have a function to save a project, call it SaveProject(). Not just Save(). Even though Save() is already way much better than Function1() which is executed when LinkButton2 is clicked. Never use the generic names your code editor suggests.

Have a good naming convention for this. Do you use SaveProject, but your Team Mate uses UpdateProject? Have a break, take a coffee and decide on which one you both should use. There is no law on what you should use, so make your own laws together. And make sure that everybody on the Team knows these laws.

You don't have time for that? Well, we'll take later. When you spend hours figuring out why your changes to SaveProject() don't work because you should have done it to the UpdateProject() function which is in the same file.

Keep names short and simple

Of course, you can go to far with descriptive naming. Your fellow developers will understand what SaveProject does. No need to call it SaveProjectToDatabase(). Unless there could also be a SaveProjectToWebservice().

Similar with variable names: don't add the datatype, like strDescription or dblPrice. Most of the times the name itself is self explanatory. And if note, code editors will tell what the datatype is.

Only if there could be ambiguity. Yes, then you should definitely add it. For example, Submitted. That could be Submitted, yes or no. Or it could be Submitted on a certain date. For the first one, use something like IsSubmitted. The second one could be SubmittedDate.

Good indentation

Good indentation makes code more readable. If something is inside a function, give it one indentation so it's clear that it is inside of it. Do you have an IF statement or a LOOP inside that function? Be sure to give one indentation more to what is inside of it.

This is especially true when you have multiple parentheses. Use linebreaks and indentation to make it easy to understand which opening ( goes with which closing ).

Use Single Responsibility Functions

Avoid using too many lines in one function. Let's say you have a Registration form and when the user submits the form it should be saved in the database and send out an email confirmation.

Separate those actions into a SaveRegistration() and a ConfirmRegistration() functions. Then call these two in the SaveAndConfirmRegistration() function.

Refactor your code

Your focus should first be on making it work. So write your code and test if it works as you expected. Does it work? Good, that is the first part of the job!

The next step should be refactoring your code. Check for unnecessary lines you might have put in there just for debugging purposes that can be removed. Maybe you should go for a SWITCH statement instead of multiple IF's. Maybe the naming can be better.

Always, first make it work and than refactor. It is worth the extra time and don't feel ashamed. Nobody get's it perfect the first time. Taking a few minutes of your time to refactor and it will save you hours when you have to fix a bug a few months later.

Comment when necessary

Comment when necessary. With the emphasis on necessary. Comments are there to help yourself later on, and for your Team Mates that will work on it as well. The comments are not there for a user or your manager.

Take a look at this example:

// This function saves the project using the ID provided:
void SaveProject(projectID)
{
Some code here...
}

The comment line is completely unnecessary. If your co-workers do not understand what SaveProject(projectID) does, the comment line wont help either. Then it is time to get better co-workers or find yourself another job.

Always when you are about to add a comment, ask yourself: “How can I improve the code so that this comment isn’t needed?".

Delete unnecessary code

When you have to rewrite something, always start by commenting out the original code. That way you know what to remove afterwards. Then rewrite it and check if everything still works as expected. When it works, don't forget to remove the original part you commented out. Also check for other lines that might now be obsolete and remove them as well.

Obsolete code should be removed as soon as possible. Simply because it will never get done afterwards. If you want to have a look back at it later, just look for it in your source control in the previous version.

And last: Work together

Share your code with others, especially when you are in a team, and learn from the feedback. Read their code as well and help them improve as well. Discuss the coding conventions and don't be afraid to improve yourself and others.

And remember: The most time spent when making software is not spent on coding, but on fixing things later.

You can leave a comment or send a question to andre@andrespeek.com. Let me know if you got inspired and stay safe and healthy always!