Best Practices
There are many different ways to do the same thing in code. However, it’s useful to stick to certain conventions to ensure you and other programmers can easily understand the code you write. Here are a few guidelines:
Don’t use magic numbers
Oftentimes we will need to use numeric literals in our code, like so:
float CircleCircumference(float radius)
{
return 2.0f * 3.14159f * radius;
}Using 2.0f in the code above is OK, since this inherently part of the formula for circumference. But we might need to use Pi (3.14159f) in a LOT of different places. Instead of having that number just hang out in our code, we could make it a constant, and put it at the class level rather than inside a function:
class WhateverItDoesNotMatter
{
const float pi = 3.14159f;
float CircleCircumference(float radius)
{
return 2.0f * pi * radius;
}
}What is that keyword above? const is a way to create literals in our code that we can refer back to, without accidentally changing their value. This is enforced by the compiler; if we tried to assign a new value to pi, we would get a compile error. But we can still use it’s value just as we would a variable.
Remove Redundant Code
What’s wrong with the code below?
//pretend that we have an integer
//called x somehwere in our code
if(x == 10)
{
//do thing
}
else if (x != 10)
{
//do something else
}The else/if portion is redundant! You only need an else:
//pretend that we have an integer
//called x somehwere in our code
if(x == 10)
{
//do thing
}
else
{
//do something else
}You should NOT do this second check “just in case”. There are only two answers to the question: either x IS EQUAL TO 10, OTHERWISE it is NOT, FOR SURE. Don’t overcomplicate things!
Use Descriptive Names and Correct Cases
Remember that circumference function we made earlier? Here’s an example of how NOT to write that code:
const float p = 3.14159f;
float circ(float R)
{
return 2.0f * p * R;
}From glancing at this function, I don’t know what it does, or what the variables represent. It’s much easier to write out the names of variables, and use casing a bit to give hints about what things ARE:
const float pi = 3.14159f;
float CircleCircumference(float radius)
{
return 2.0f * pi * radius;
}The function name is capitalized and uses CamelCase (where separate words in the function name are separated using capitalization). The variable names are lower-case, and longer than a single letter. They’re descriptive enough to let us know what they’re used for in this function.
Indentation and Braces
Remember to indent when you create new scope:
bool RockFact()
{
bool fact = true;
while(true)
{
if(fact)
{
Console.WriteLine("That's a rock fact!");
}
Console.WriteLine("Greg, you're getting us into trouble again!");
}
}If you MUST put a brace on the same line as a while loop or if statement… fine. But I’ll hate you for it.
if(terrible) {
Console.WriteLine("Ugh, this is super ugly code")
}Volcano alert! Volcano alert! Volcano alert! Volcano alert! Volcano alert! Volcano alert!
if(isBad)
Console.WriteLine("Into the chokey with you!")If you write the code above, we’ll visit this website: https://www.volcanoesandearthquakes.com/?hideQuakes=1
There are other code quality and style guidelines to keep in mind, and we may visit those later. But for now, let’s visit one last thing related to organizing and understanding code.