I've been around the block on other peoples code a few times now and i gotta say the state that some people call "code" ranges from a form of art to vomit inducing. But today, i am going to focus on that lesser end of the spectrum. This post is dedicated to those that need a stern telling off for their horrible code.
When naming anything in code you have two standard options: snake case, and camel case. Snake case uses underscores to represent breaks in words (for example, days_in_the_week), whereas camel case uses capital letters to instigate the start of a new word (for example, daysInTheWeek). Now I'm not going to sit here and tell you which one is correct to use, because its down to preference. I am, however, going to tell what not to do.
First, DONT MIX THEM. PICK ONE. STICK TO IT. You have no idea how many headaches people have whilst creating a new function using existing variables just to find they have been named in a different way. Second; when using snake case, if you are going to use hyphens instead of underscores, stay consistent in your code. Don't go switching them, and ideally use underscores, because some languages do not support hyphenated variables. Thirdly, when using camel case, make sure you always start a deceleration with a lower case letter (for example, numberOfUnicorns not NumberOfUnicorns) or at least stay consistent with your syntax if you are going to use a non standard format.
Just use them. JavaScript may not require you to use semi-colons, but not using them can more often than not end up in random and weird bugs. Just make everyone's life a little easier, I mean its only one more keypress stop being lazy. Alternatively, if you are developing a node application, implement and follow the rules of a JavaScript linter.
Ok we aren't going to have a tabs vs space argument. We aren't. It's not going to happen. However, when using spaces, make sure you use the same amount of spaces in each function, as some languages are sensitive to this and may error out if you don't make sure the amount of spaces is standardised. Of course, you wouldn't have this problem with tabs. Just sayin'.
Consistent whitespace is important in your code, as it makes it much easier for a user to read through your code, and visually identify where functions start and end. Make sure you pick a method of indentation and code separation and stick to it.
Side note: if you ever want to break up parts of your code into separate sections to assist your user, use a commented line of characters, (eg, //---------------) to separate different sections of code. A physical line drawn between code can help people to identify where a section of code starts and ends.
Ok, this one is a little more subjective. A lot of people suck at writing comments for their code. First, for the sanity of others, YOU HAVE TO COMMENT. Obviously not every line, but you do have to. Un-commented code is a nightmare for developers to pick apart and troubleshoot, and you can save countless hours of peoples time in a couple minutes by adding some good quality comments. Here's a shortlist of reasons to leave a comment in your code:
Once you have figured out what you want to comment, you need to pick a style of commenting. This is largely subjective, but some simple rules are include using single line comments for single lines, and multi line comments for comment blocks. This can be difficult as not all languages equally support commenting styles, but as with anything else, make sure you pick a style and stay consistent.
Here is a simple example of a well commented, although overdone, piece of pesudocode:
function printValue(x){
/*
this function is used to print a value
to the terminal. it is passed in value
'x' and prints it to the terminal window
*/
// assign value x to a string
string output = str(x);
// print the value
print(x);
return 0;
}
And that's it for now! Just a few things that are in shared source code that rub me the wrong way. What do you think? Do you agree? Are there any other more annoying things people do that you can think of? Who knows, maybe ill write another one of these..