Rob Kraft's Software Development Blog

Software Development Insights

Archive for May, 2016

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

Posted by robkraft on May 22, 2016

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.

CodeArt10-1

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.

CodeArt10-2

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.

 

Advertisements

Posted in Code Design, Robert's Rules of Coders, Uncategorized | Leave a Comment »