Robert’s Rules of Coders: #10 Scope minimally, scope private

A big ball of mud is a designation for some software programs that are very difficult to maintain. We never set out to create a big ball of mud, but it happens to many programs over time. One technique to reduce the entanglements that lead to a big ball of mud is to expose the functions in your code as little as possible to other parts of your program. In many programming languages the term “scope” is used to determine if your function can be used anywhere within the program, or just within a small area of the code.

The two most common scopes are “public”, which usually means that any part of your program, and perhaps other programs, can call the function; and “private”, which usually means that only other functions within the same region of code, within the same “class” or “namespace”, or perhaps within the same compiled assembly can call the function.

Some languages include additional scopes such as “internal”. .Net allows methods that are scoped private to only be called by other methods within the same “class”; but the use of the “internal” scope allows other classes within the same compiled dll to call the methods with an internal scope, but code in other dlls cannot.

When you write a method that is only used within one class, you should always set the scope of that method to private. This provides the following benefits:

1. You do not unintentionally provide access to sensitive data.
2. The code will not be accidentally called from another class, by another developer or yourself, creating an unexpected and undesired entanglement.
3. The code will not be called by third-party developers, particularly if the class you are writing is part of an API that you expose to third-party developers.
   1. Of course, if you desire that third-party developers have use of the method then scope it public, but do not do so by default because you may be unable to change the method in the future without breaking the third party dependencies on your API.
4. If you have scoped the method privately, you can be sure that other code is not using the method if you later decide to refactor or rename the method.
   1. This is not entirely true for languages that support alternate methods of calling even private functions from outside of the functions class. For example, the .Net language provides a feature called reflection that can be used to call the private members of another class. Developers using the reflection technique usually understand the risks.
5. If you have a method that could be accessed by another class, you should spend a few minutes reconsidering the design of your classes instead of quickly and simply making the class public.
   1. Perhaps you should create a new helper class; perhaps you should refactor the code in the method to make accessible just what is needed in the other class.

In the two examples below, the developer desires to use the Base64Decode method in another class.  In the first example the ExampleOfWhatNOTtoDo class is made public as are all of the methods.

But it would be better to move the Base64Decode method out of the ExampleOfWhatNOTtoDo class, so that nothing is made public that does not need tobe public as shown below.

When the language allows a level of scoping besides public and private, such as internal, you should generally consider changing the scope from private to internal if that is sufficient rather than from private to public.

I have two final tips for .Net developers.

Tip 1: You can scope methods internally, yet allow other applications that you write have access to them but using “Friend” assemblies as described here: https://msdn.microsoft.com/en-us/library/mt632254.aspx. The InternalsVisibleTo attribute can be provided to the class in code or to the entire dll in the AssemblyInfo.cs file.

Tip 2: You can use an interface for internal methods, thus making your methods accessible through an interface from other dlls in your solution. You just need to explicitly implement the interface as described here: https://msdn.microsoft.com/en-us/library/ms173157.aspx.

As with any of Robert’s Rules of Coding, you don’t need to adhere to them all of the time and there are cases where it is better not to. But most programmers should follow the rules most of the time. I hope you agree.

Go to Robert’s Rules of Coders for more.

 

Robert’s Rules of Coders #9: Eliminate Deep Nesting by Using Switch Statements and Functions

The ‘If’ statement is one of the fundamental coding constructs of almost every programming language. Along with the ‘If’ statement, most languages also support ‘else’ conditions and the ability to nest ‘If’ statements. But this simple construct can also become one of the biggest contributors to code that is difficult to understand and modify. This often happens when ‘If’ statements get nested within ‘If’ statements; but there are two simple techniques you can use to reduce this complexity, ‘Switch’ statements and functions.

Switch statements offer these benefits to most developers:

• They are easier to read, and thus
• They are easier to understand, and thus
• They are easier to maintain.
• They are also easier to debug
• In many languages, they also can be compiled to execute a little more swiftly that nested ‘If’ statements

Here is an example of an ‘If’ statement than can be improved by converting it to a ‘Switch’ statement:

If aValue = 6 then

Stars = stars + 1

Else

if aValue = 7

Stars = stars + 3

Else

if aValue = 8

Stars = stars + 5

Else

if aValue = 9

Stars = stars + 9

End if

End if

End if

End if

Here is the same logic from above, using a ‘Switch’ statement:

Switch aValue

Case 6:

Stars = Stars + 1

Case 7:

Stars = Stars + 3

Case 8:

Stars = Stars + 5

Case 9:

Stars = Stars + 9

I suspect that you will agree that it is easier to understand the code in the switch statement than the code in the nested ‘If’s. Another technique to eliminate nested ‘If’ statements is to move some of the code into separate functions. Although the hierarchy of ‘If’ statements may remain the same from the computer’s point of view, to most humans it becomes much easier to manage.

If input data is valid

If filename is valid

Create File

If file was created

Log “Success”

Return “Success”

Else

If error due to size

Log “Failure”

Return “Could not create file because it is too large.”

If error due to permission

Log “Failure”

Return “Could not create file because you do not have permissions.”

Else

Log “Failure”

Return “Unable to create the file. Reason unknown.”

End if

End if

Else

Log “Failure”

Return “Your file name is invalid.”

End if

Else

Log “Failure”

Return “The file input is invalid.”

End if

Here is the same logic from above, using functions:

String response = “”

Response = IsInputValid(myinput)

If (response= “”)

Return response

Response = IsFileNameValid(myfile)

If (response= “”)

Return response

return FileCreationResultMessage(myfile, myinput)

The functions called from the code above:

Function string IsInputValid(string input)

If input is not valid

Log “Failure”

Return “The file input is invalid.”

Else

Return “”

End if

End Function

Function string IsFileNameValid(string input)

If input is not valid

Log “Failure”

Return “Your file name is invalid.”

Else

Return “”

End if

End Function

Function string FileCreationResultMessage(string file, string input)

Create File

If file was created

Log “Success”

Return “Success”

Else

If error due to size

Log “Failure”

Return “Could not create file because it is too large.”

If error due to permission

Log “Failure”

Return “Could not create file because you do not have permissions.”

Else

Log “Failure”

Return “Unable to create the file. Reason unknown.”

End if

End if

End Function

As with any of Robert’s Rules of Coding, you don’t need to adhere to them all of the time and there are cases where it is better not to. But most programmers should follow the rules most of the time. I hope you agree.

Go to Robert’s Rules of Coders for more.

Robert’s Rules of Coders: #8 Avoid Negative Conditionals And Method Names

When you write code you should almost always assume that another person will attempt to read and understand that code some day in the future. That person could be your future self. Therefore, it is in your best interest to write code that can be quickly and easily understood by people, in addition to providing the correct instructions to the computer. Two ways to do this are to avoid negative conditions and negative words in method and variable names.

Avoid Negative Conditions

Let’s consider the following two ways you could write a bit of logic:

You could write:

If a > b then… //If a is greater than b

Or you could write:

If a !<= b then.. //If a is not less than or equal to b

 

A computer will understand both ways equally well, but it usually takes humans a little longer to understand the second way than the first. And when another developer adds a little more logic to the statement it takes humans even longer to figure out as shown in the next two statements:

 

You could write:

If a > b and c > a then… //If a is greater than b and c is greater than a

 

Or you could write:

If a !< b and c !< a then… //If a is not less than or equal to b and c is not less than or equal to a

 

When developers see the second way above they will probably write down numbers on a piece of paper to help them deduce the logic, even though ultimately it is the same as the first way. Of course changing the sequence of the conditions can also make the logic more readable, but in some languages that may come with a performance impact.

 

Consider Performance Impact of Condition Sequence

You could write:

If a > b and c > a then …

 

As

If c > a and a > b then …

 

Both ways provide the same output, but many languages will only evaluate the second condition if the first condition is true. This happens because the language is smart enough to realize that if the first half of the statement is false then the entire statement will be false. So in some cases, like in the methods below, it is probably more efficient to write the code the first way than the second way even though the results are the same:

 

The first, more efficient way to write the code:

If FastMethodThatReturnsTrueHalfTheTime() == true and SlowMethodThatUsuallyReturnsFalse() == true then…

 

The second, less efficient way to write the code:

If SlowMethodThatUsuallyReturnsFalse() == true and FastMethodThatReturnsTrueHalfTheTime() == true then…

 

 

Avoid Negative Words in Method Names

We often include method names in our ‘if’ statements and therefore we should probably avoid negative terms in the names of our methods. Consider the following examples of a method that checks for hyphens in a string:

 

String streetName = “Happy-Road”

If StringContainsHyphen(streetName) Then …

If StringDoesNotContainHyphen(streetName) Then …

 

The two statements above both seem easy to understand, but what happens if a coder checks if the results are false? Notice that it gets more difficult to interpret the second statement that contains the negative word “Not” in the name.

 

If StringContainsHypen(streetName) == false Then …

If StringDoesNotContainHypen(streetName) == false Then …

 

Avoid Negative Words in Variable Names

The guidance to avoid negative words in method names holds similar value for variable names, particularly the names of boolean variables.

 

We could name a boolean blnCountExceedsMaximum, or blnCountDoesNotExceedMaximum. We could also name it blnCountIsBelowMaximum or blnCountIsNotBelowMaximum. Now look at the following four statements and decide for yourself which is easiest to understand.

 

• If blnCountExceedsMaximum == false then …

• If blnCountDoesNotExceedMaximum== false then …

• If blnCountIsBelowMaximum == false then …

• If blnCountIsNotBelowMaximum== false then …

 

If you are like me, the second and fourth statements take a little longer to understand than the first and third.

 

Should you include “Is True” and “Is False”?

I have one last topic I think you should consider when writing ‘if’ statements. Should you include the “== true” and “==false”, or just leave the variable without that? A lot of languages do not require those values. The computer handles the following two statements equally well.

 

If blnSuccess == true

 

If blnSuccess

 

Personally, I don’t think it usually matters too much and I tend to code both ways. Sometimes, usually when my if statement has a method call in it or multiple conditions in it, I will include the “== true” or “== false” because I believe it adds clarity:

 

If (ExportDataToFile() == true and LastExportSucceeded == false) then

 

If you are going to test if a non-boolean variable is true or false, then I recommend including the “== true” or “== false” to let the next programmer know that this is what you intended.

 

//You could test if “number of failures” is not equal zero this way

If NumberOfFailures == true

 

//Or you could test if “number of failures” is not equal zero this way

If NumberOfFailures

 

In the second statement, it is not obvious that you intended to test the number as a boolean. Another programmer looking at the code might think you accidentally left part of the code out of the program. Rather than use either of those statements, it would probably be best to write:

 

If NumberOfFailures != 0

 

As with any of Robert’s Rules of Coding, you don’t need to adhere to them all of the time and there are cases where it is better not to. But most programmers should follow the rules most of the time. I hope you agree.

Go to Robert’s Rules of Coders for more.

Robert’s Rules of Coders: #7 Use Constants For Values That Don’t Change

All programming languages, at least that I know of, support the concept of variables that are used to hold values that change while the program is running.  But a lot of cases exist where we need to define a value to our code even though that value will not change as the program runs, and we have three options for providing this value.

We could simply code the value (3.14 in this example) where it needs to be used:

Circumference = 3.14 * diameter

We could create a variable and assign the value to the variable:

Double pi = 3.14

Circumference = pi * diameter

We can declare a special type of variable known as a constant:

Double const pi = 3.14

Circumference = pi * diameter

Of the three options above, using a constant is usually the best option for several reasons.

Variables over values

First of all, if the value will be used in many places in the program, you will often save yourself time by placing the value in a variable or a constant so that if the value ever changes you only need to change it in one place.  You may decide that instead of using 3.14 that you prefer to use 3.14159 in the calculations.  If your variable is a string for a format such as “mm/dd/yy” you may decide later that you want the format to change to “mm/dd/yyyy” and using a variable or constant makes the change easier, and more accurate because you are less likely to overlook some.

Use Variables To Make Code Changes Easier

Second, when changing the value you are less likely to change the wrong value when you use a variable than if you use a value.  In the example below, you are less likely to change the tax rate from 3.14 to 3.14159 if you are using a variable than if you are using a value.

Variable Help You Change The Correct Value

Third, variables make your code more readable. Many people may know that Pi is 3.14 and recognize the value in code, but few would recognize the number 8 as representing the number of planets:

• For I = 1 to 8
• //do some code
• Next I

Is less clear in meaning than the following:

• For I = 1 to NumberOfPlanets
• //do some code
• Next I

Constants Instead of Variables

Values that won’t change while the program is running can be defined as “constants” in most programming languages. This informs the compiler that the value will not change and the compiler can make the program a little more efficient. Often, what the compiler does is the equivalent of a find/replace everywhere the constant is used. This means that the variables will not need to be placed on the memory stack reducing the RAM required by the program to run.

By declaring that your variable is a constant, you also ensure that your own code does not attempt to unintentionally change the value of the variable while the program is running.

Here are some examples of good places to use constants instead of variables:

• When your program has a name that you show on Title Bars and in log file messages such as:

String const PROGRAMNAME = “My Program Name”

Note: some languages have conventions for constant names such as using all upper case letters for the name. I recommend following the conventions of the language you code in.

• When your program formats a value in many places, especially if that format may ever change:

String const DATEFORMAT = “mon , dd, yyyy”

• Values that almost never changed that are used in multiple places:

Int const NUMBEROFSTATES = 50

• Messages or part of messages that occur frequently in the code.  This also helps you reduce the number of spelling errors.

String const ERROROCCURREDHEADER = “An error has occurred!”

When you write programs that have code in multiple assemblies, or projects, or dlls, you may want some constants to be used across the whole program, and others used just within a single assembly.   Use scope and careful naming conventions to correctly place those constants.  If a constant will only be used within one assembly, then declare the constant within that assembly and don’t make it globally accessible.  If you want the same constant used by several assemblies, place it in an assembly all the others can reference and give it a good name like GlobalConstants.

Solution for Program with Three Projects:

• Project1 named SharedAlgorithms
  • Contains a class named GlobalConstants with these constants:
    • String const ERROROCCURREDHEADER = “An error has occurred!”
    • String const DATEFORMAT = “mon , dd, yyyy”
• Project2 named TaxCalculations
  • Contains a class named TaxConstants with these constants:
    • Double const TAXRATEFORMISSOURI = .08
    • Double const TAXRATEFORKANSAS = .12
• Project3 named AppUI
  • Uses the constants from the SharedAlgorithms project, but not the constants from the TaxCalculations project because it does not need any of those values.

Warning: In many languages, you need to recompile both the AppUI project and the SharedAlgorithms project in the example above if the GlobalConstants are changed.  If you don’t, AppUI will continue to use the values the constants had at the time it was compiled, not the values the constants in SharedAlgorithms currently have.

Go to Robert’s Rules of Coders for more.

Robert’s Rules of Coders: #6 Don’t Use Magic Numbers

When someone refers to a magic numbers in software, they probably have one of the following three scenarios in mind:

• A value that is used to determine the behavior of the code, but the value itself provides no meaning
• A value that has been hard coded in several locations in the program, that is unlikely to change, but might
• A value that is well known in some software and that will not be changing

Using a magic number directly in your code can lead to problems and it is recommended that you avoid or minimize the use of them.  Let’s examine each of the three types of magic numbers and the risks associated with using them.

Example One with Magic Numbers

The first type of magic number in the above example is the value for the AccountType.  When looking at the code, most programmers will not know what the values of 1, 2, and 3 represent.  This type of magic number is common when the programmer is comparing the AccountType to a value that has come from a database or file and the value was persisted as a 1, 2, or 3.  But many programming languages today support the concept of an enumeration, or enum, that can be used to make the code more readable:

Example Two Eliminating A Magic Number

Using an enumeration in place of a hard-coded magic number offers several advantages:

• The code is easier to understand for humans. The code is easier to write for humans because we don’t have to reference documentation elsewhere to know what an AccountType of 1, 2, or 3 means.
• It is easier to alter a value. If the source of the data decided that the value 2 should represent “No Taxes” and 3 should represent “No Federal Tax”, the code could be adjusted where the enumeration is defined.  That is much easier than searching all of the code to replace 2s with 3s and 3s with 2s.
• It is easier to review the code where the enumeration containing all of the possible values are defined for accuracy and completeness.

The same block of code above also includes another type of magic number with the values of 1.1 and 1.03 to represent tax rates.  I suspect you already realized that hard-coding the tax rate is risky because the values change so often.  But some magic numbers are less obvious such as in this example:

Example Three with a Magic Number

In this example the magic number is the number 50.  There are 50 states in the USA as I am writing the article, but that number could change.  If you have coded the number 50 representing states in several places in your program, someone will need to change them all if that number of states changes.

Example Four Without Magic Numbers

Using constants to eliminate this type of magic number provides several advantages:

• The code is easier to understand for humans. We know right away that we are looping through the number of states and don’t have to question what the value of 50 represents.
• It is easier to alter the value. If the USA adds one more state we can change the constant defined in one place in the code and be done with our changes. A programmer could do a find and replace across all of the code on the value 50 easily enough, but the number 50 might be used in other places referring to something other than the number of states in the USA.
• A developer could accidentally type 60, 500, or even 49 instead of 50 and the compiler would allow the code to compile without warning.  This problem is less likely when the important value is only coded once and a variable name is used throughout the program.

The third class of magic numbers are numbers that indicate types of files or the beginning and ending of streams of bits in protocols.  These magic numbers are generally dependable, but you should still avoid coding them in the flow of your code logic primarily for readability.  One example is the use of FFD8 and FFD9 at the beginning and ending of JPEG files.  Instead of hardcoding this magic number inline in the code:

Example Five With Magic Numbers

Consider defining a constant to improve readability.

Example Six Without Magic Numbers

There are some drawbacks to eliminating magic numbers, but the benefits of eliminating them usually outweighs the drawbacks.  Drawbacks include:

• The programmer might want to know the value of the constant or enumeration and would need to refer to where the value is defined to discover it.  This could take a little time if the constant or enumeration is not defined closely to where it is being used.
• It makes the source code a little bit longer. In compiled languages, this is almost never a concern, but it non-compiled languages like javascript it might have a small impact on performance.

Go to Robert’s Rules of Coders for more.

Robert’s Rules of Coders: #5 Organize Your Code

When you write programs that consist of many lines of code, where the threshold of “many lines” probably begins around fifty lines of code, you should consider organizing your code in ways that will make it easier for you to maintain it in the future.  Breaking the code into many functions is a good start, but when you have a lot of functions it can become difficult to manage and remember them.  At this point you should consider grouping related functions, and in most programming languages placing the groups of related functions into separate files.

The major benefit is that you, and other developers, can more easily find the code you are looking for when you want to examine or modify it.

You may consider placing all functions you use to generate and send emails into a single file that you name Email.Code.  You may move all of your functions for formatting strings into a file name StringFormatting.Code.  Organizing your code into separate logically grouped files provides the simple benefit of helping developers find the code to be worked on more quickly.  For example, if you are on vacation and I need to fix a bug related to emails in your code, I can find the bug more easily if the email code is in its own file than if all of the program code is in one single large file.

Having many separate files for your code also helps you track changes in the code when you are using a source code control system; which you should be doing.  For example, if I made a change several months ago to the Email.Code and I now realize that my change might have broken something, I can use my source code control system to review the changes made to Email.Code more easily than I can use it to review the changes to All.Code.

Business developers often use the technique of object oriented programming to help determine how to organize their code into separate files.  The programmer may put all the code related to customers in Customer.Code, and all of the code related to products in Products.Code.  Although placing code in separate files is not what object oriented code is really about, it is a natural side effect.  Large object oriented applications may use several files for a single “object”. Instead of just a single file for Customers, the code may be broken into several files such as CustomerProperties.Code, CustomerPersistence.Code, and CustomerBusinessRules.Code.  Once again the primary reason for multiple files is usually because programmers have learned that many small source code files are easier to develop with than a single large file of code.  Another benefit when there are multiple developers may be that each developer focuses on a different area of expertise and one developer focuses on …Persistence.Code files and another developer focuses on …BusinessRules.Code.

An additional approach to organizing code, and I choose the word additional because it could and should be used along with organizing code by object and function, is to group code in different layers of the application architecture together.  Many applications today consist of at least three layers:

• a User Interface (UI) layer,
• a business logic layer,
• and a data persistence layer that stores data in files or databases.

It is very beneficial for developers to keep the code in these layers separate because it makes it easier for the developer to make some changes in the future.  On such change could be storing data in a different type of database.  Another could be replacing the desktop UI with a web page UI.

In object oriented development, developers following the SOLID principles, will implement the “Single Responsibility” principle which leads them to limiting each “class” to doing just one thing, hence the term “Single Responsibility”.  Although this does not necessarily dictate that a developer will only have one class per file, that is often the case and thus followers of the “Single Responsibility” pattern are likely to organize code into separate manageable files.

So instead of placing all of your code in a single file like this:

File1: AllMyCode.code

All Code in One File

Break the code into separate files like this:

File1: UICode.code

Code In UICode.Code file

File2: ProductCode.code

Code In ProductCode.Code File

File3: CustomerCode.code

Code in CustomerCode.Code File

File4: EmailCode.code

Code In EmailCode.Code File

Go to Robert’s Rules of Coders for more.

Robert’s Rules of Coders: #4 Make Functions Short

Functions are easier to understand and thus easier to maintain when they are short.  You can often make functions shorter by finding patterns in a large function and extracting those lines of code comprising the pattern into a separate function and calling the separate function as shown below.

One Long Function

One Short Function With The Same Results

Note: The FormatForOutput function is not shown because I believe you can figure out what it does.

But even when you have a long function with no lines of code that are duplicated, you can often make the code more readable and easier to maintain by separating the code into functions.  Consider this example:

One Long Function

Long Function Broken Into Short Functions

Note: The 4 new functions are not shown because I believe you can figure out what they do.

Most developers will be able to understand the 2nd example better than the first.  But there is another big benefit that applies in a lot of languages.  Let’s assume that an error occurs with a message of “Object variable is null”.  In the first example, the error message might show a call stack that says our program named Program1 called the method MainCodeBlock and this error occurred within MainCodeBlock.

Call Stack from First Example:

• Program1
  • MainCodeBlock

But which line of code within MainCodeBlock?  We don’t know and it could have been caused by many of the lines.  However, if the same error occurs in the second example, our call stack would look like:

Call Stack from Second Example:

• Program1
  • MainCodeBlock
    • SavePriceToDatabase

In the second example, we have narrowed down the problem to the SavePriceToDatabase method and have only a few lines of code to consider as the source of the error.  This is another benefit of smaller functions.

Finally, for those of you that write unit tests as most good programmers should, you have functions neatly wrapped up and ready to be called by those unit tests.

In summary, short functions provide these benefits:

• They organize your code, making it easier to understand and maintain.
• They make it easier to pinpoint bugs when you have a call stack.
• They make it easier for you to write unit tests for your code.

Go to Robert’s Rules of Coders for more.

Robert’s Rules of Coders: #3 Use Good, Meaningful Names

Code is much easier for humans to read when the variable and function names reflect what they mean and do.  In ancient times, like the 1960s, some programming languages did not support long variable names, but today most every language supports long names with no penalties.  Although some exceptions may be tolerated for very common usages such as the variables “I”, “j”, and “k” for loops, you should strive to use meaningful names in all cases.  Would anyone honestly say that the first block of code below is easier to understand than the second?

Code with and without good names

Good, meaningful names not only make your code more readable, but they may also remove the need for you to add comments or documentation to the code.

When we first began writing javascript in the 1990s we used short variable names because we wanted to reduce the size of the files to make them faster.  Today, you should probably not do this because the data is compressed by default by technologies like gzip, and Internet speeds are faster, and if you are writing enough code that the size of your javascript is a factor you should be using a minifier tool to make the javascript smaller for you.

Aside from long names, what makes a variable or function name good?

•  Good names reflect the value stored in the variable or explain what the function does. “Counter1” is better than “c”, but “ActionCounter” is even better. Giving variables relevant names reduces the time it takes people in the future looking at the code to figure out what it does. And that includes the future you. This applies to function names also. A function named “UpdateActivityCount” is better than “CountUpdater”.
• Try not to use negative logic in variable and function names. It takes our brains a little longer to deduce the meaning of negative logic statements.
  • IsValid is usually a better name than IsNotValid
  • DoesValueExceedMaximum is usually better than DoesValueNotExceedMaximum
• Follow the conventions of the language you are coding in. If the language uses CamelCase, you should use CamelCase. If the language uses Hungarian Notation (txtFirstName, intItemCount), you should use Hungarian notation. If the language uses all upper case for the names of CONSTANTS, you should use all upper case for CONSTANTS too.
  • In javascript, most variables and functions start with a lower case letter. Global variables should be all caps.
    • Source http://javascript.crockford.com/code.html
  • In C#, do NOT use Hungarian notation. Do not use abbreviations.
    • Source https://msdn.microsoft.com/en-us/library/ms229045
  • In Java, use a lower case first letter and mixed case. Use all upper case for constants.
    • Source http://www.oracle.com/technetwork/java/codeconventions-135099.html
• Don’t reuse variable names for different purposes.

Example of Reusing a Variable

• The function name should describe what it does not how it does it.  This allows you to change how the code in the function works without needing to change the function name. This helps the function remain a black box.
  • Name the function GetAllCustomers, not CallDatabaseUsingADOtoGetDataFromCMCUSTTable.
• Avoid names that might match keywords. Naming a variable “Name” or “Date” might compile safely at first, but it might fail after an update to the language is installed, or if you include a new library in the project. Also, it may not be obvious to other developers that the variable name is one that you created instead of one that is built in.
• Follow a consistent pattern
  • If your Foo object has a Retrieve method to get data from the database, then your Bar object should also have a Retrieve method to get data from the database, not a Get method. Using the same method and property names across objects when the methods serve the same functions reduces the learning curve for new developers.
  • You should also strive to use consistent noun and verb pairings.  Naming two functions CalculateLastSaturday and CalculateLastSunday is usually easier for programmers to remember than having one function named CalculateLastSaturday and the other named FigureOutFinalSunday.

Finally, remember to rename your variables if the meaning of the value they store changes and rename your functions if the things the function does changes.  We are writing code for humans, not for computers.

Are there any more good rules that should be added to this list?

Robert’s Rules of Coders: #2 Avoid Global Variables

Global variables are variables that can be accessed from anywhere in the program.  It is appropriate to use a global variable when you have a value that is a constant and thus won’t change as the program runs, but it is rarely appropriate to use global variables for values that change while the program is running.

Functions should usually return the same output when given the same inputs.  Global variables in functions can cause the function to return different values, making the function less reliable and more difficult to write unit tests for.

A Bad Program With Global Variables

In the block of code above, you can see that the value returned from CalculatePrice() is not predictable.  In the first case it returned 11.00, but in the second case it returned 10.50 for the same inputs.  Here is a second version of the program:

Same Program Without Global Variables

The second version of the program has the following advantages:

• The programmer can see all the factors that affect the TotalPrice.  None are hidden.
• The programmer can write unit tests against the CalculatePrice() function more easily.
  • Assert.That( CalculatePrice(4, $2.5, 10%) = 11.00)

The problems with using global variables include the following:

• Global variables can be modified from anywhere in the program, making the output of functions using them less predictable
• Rules that you code in one place about setting the value of a global variable may not be adhered to in other places. For example one block of code may do this:

Setting Global From Spot 1

But another block of code in the program may do this:

Setting Global from Spot 2

• A function or component that uses global variables becomes “tightly coupled” to the other components that use the global variable.  This entanglement increases programmatic complexity which means the program is probably more difficult to maintain and enhance, and also that it is difficult to replace one component of the program without affecting others.
• In multithreaded programs, global variables may not be thread-safe.
• In some languages, global variables make it difficult to add new components to an existing program because the new component may contain its own global variables with the same name.

When you have an object that you think should be global so that it can be used everywhere, you should probably use Dependency Injection.  Don’t be deceived by the Singleton pattern for a global variable replacement because that often becomes just a more complicated version of a global variable.

Robert’s Rules of Coders: #1 Write Subroutines Profusely

Most programming languages support the concept of a subroutine.  A subroutine is a block of code that your current code calls (aka executes) to run some more code.  Subroutines are called by many different names, with some of the most common being ‘function’, ‘method’, or ‘procedure’.

Subroutines serve two primary purposes:

1. They allow you to easily reuse some of your code
2. They organize your code, making it easier to read and maintain.

A program without subroutines

A Program Without Subroutines

A program with subroutines

A Program With Subroutines

The advantages of the program that uses subroutines include:

• The code is easier for another person to read, and that other person could be the future you.
• Code that is re-used provides these benefits
  • You spend less time writing code because you can use code that already exists, the subroutine that you wrote.
  • The subroutine is already proven to work when used the first time.  You won’t have to spend time fixing logic errors and typos each subsequent time you want to do the same things.
  • If you discover a bug in the subroutine you can fix it in the subroutine which fixes it for all places from which it is called. In the first program above, if you found a bug formatting Item1PriceOut the same bug would probably also exist in formatting Item2PriceOut and need to be fixed there too.
  • If you decide something should be changed, such as using “<strong>” instead of “<b>” when formatting your string you can make the change once instead of making it in several places.
  • You can optimize the code later. Perhaps you later learn that you can call ConvertToDollars() and the formatting to two decimal places will be handled for you. You can make the change in the subroutine instead of making the change several times as you would have to do in the first program above.

Easily Change a Subroutine

• The subroutine is more likely to be testable from an automated test.  Many languages allow you to write “unit tests” that can be run regularly to insure your code keeps working as intended even after you make changes to it over time.  It is easier to unit test code isolated in a subroutine than it is to unit test code that is just part of a larger code block.
  • Example Unit Tests:
    • Assert.That( FormatForOutput(7) = “$7.00”)
    • Assert.That( FormatForOutput(7.1) = “$7.10”)
    • Assert.That( FormatForOutput(555) = “<b>$555.00</b>”)
• The size of the code is usually smaller when using functions, taking less disk space.
• The size of a compiled version of the program is probably smaller, taking less disk space.
• The size of the program in memory is probably smaller, using less RAM.
• The memory allocated to variables is more likely to be re-used which therefore requires less RAM.

Use Subroutines Profusely

I recommend using subroutines when you see that you have two or more lines of code that are the same over and over in the program.  One thing that makes a programmer a good programmer is the ability to see patterns.  So even though these lines of code are not the same, a good programmer will see that there is a pattern and extract that pattern into a subroutine:

Can You See A Pattern?

Becomes

Pattern Implemented in a Subroutine

In this case, the second program has more lines of code, but if you need to modify Item3PriceOut and Item4PriceOut the program with subroutines will become the shorter program.  And it will be easier to maintain.

Use Subroutines to Hide Complexity and Third Party Dependencies

Use subroutines for anything that might change and is used more than once, especially third party dependencies.  For example, if you use a third party tool called 123Logger in your code like this:

3rd Party Code Inline

Replace it with code like the following because if you ever want to change to a different logger than 123Logger, you will only need to change your code in one place.  You are writing your code so that it is not as dependent on how the third party logger software needs to be called.

3rd Party Code in a Subroutine

When you decide to use XYZLogger instead of 123Logger, you can change your code to look like this:

Using Different 3rd Party Code

There are even better ways to handle third party dependencies like this for larger applications, but this approach is a good start.