Programming Style Guide – The Need for programming standards

Programming Style Guide refers to the conventions followed while writing programs. This guide is going to be a series of blogs highlighting different programming standards. The series will try to cover as many standards as possible, focus will be on common and popular standards.

But why the need for programming standards? Standards help software developers design software in such a way that it is easy to read, understand, maintain & expand. It provides a consistent experience & also speeds up the way in which software development is done.

A program written with the best standards kept in mind is self explanatory, easy to read, can be built on, & is a stable piece of software

This specific article will act as a Content list for all the articles written as a part of this series. The examples are from the Swift & C++ programming languages.

  1. Naming Conventions
  2. Code Refactoring
  3. Programming Style Guide: Documentation
  4. Programming Style Guide: Command Query Separation

 

 

Advertisements

Programming Style Guide: Naming Conventions

Today we are going to look at Naming conventions you can follow while writing code.

Naming conventions lay down the basic rules for naming different elements in your code. The objectives are simple:

  • Make the element easy to read
  • Should be self explanatory
  • Should contain information in a compact and concise manner.

Ideally a well named variable or function should not need a comment to explain what it is for.

With the above objectives in mind let us look at some of the naming conventions that can be followed. The examples are from the Swift & C++ programming languages.

Naming Conventions

Camel Case Names

In camel case naming convention the entire name of the element is constructed by forming a sentence joined into a single word. So for example if we have a variable for keeping track of the price of oil in US dollars then the variable name might be priceOfOilUSD.

Here are some examples of naming conventions with the camel case.

SWIFT

var priceOfOil : Float = 23.49

C++

float priceOfOil = 3.45;
class PersonInfo
{

};

Underscore Separated Names

In the underscore separated naming convention the entire name of the element is constructed by forming a sentence joined together with the help of underscores in-between them. So if we take the example of the variable keeping track of the price of oil in US dollars the the variable name might be price_of_oil_usd.

Swift

var price_of_oil : Float = 45.71

C++

float price_of_oil = 99.87;

void print_value_of_pi()
{
     //print something
}

Names with type information

A naming convention that is quite popular is the one that mixes the previous 2 naming conventions, with the underscore used to separate the type description in the prefix. So if we take the example of the variable keeping track of the price of oil in US dollars then the variable name might be f_priceOfOil or float_priceOfOil. Either of the design styles work. The prefix is popularly abbreviated and you can create your own rules for abbreviating the type description.

This style is often referred to as the Hungarian notation. The additional information that is provided as a part of the prefix can be:

  • Whether the variable is a pointer
  • Whether the variable is an object
  • The scope of the variable
  • Type size
  • Whether the data can vary or is a constant

Swift

var f_priceOfOil : Float = 0.0

C++

float f_priceOfOil = 22.3;
int *ptr_memmoryBuffer = NULL; //ptr indicates variable is a pointer

Naming Rules

There are some rules that are typically followed while designing names for variables and  functions. Like the conventions themselves the rules are not binding but they are very useful an give the added punch that naming conventions provide.

  1. Variable names always start in lower case.
  2. Type names always start in upper case.
  3. The naming conventions is consistently applied through all the projects
  4. Names should be kept as small as possible without sacrificing on the description

Naming Strategies

As far as strategies are concerned there are multiple approaches that one can follow. Here are some potential strategies.

  • Follow one naming convention for variables and another convention for functions.
  • Let constants be all upper case
  • Prefix types with your companies initials.

Summary

The above illustrate just some of the naming conventions that can be followed. By no means are they comprehensive or complete. Also it is not necessarily true that everyone follows the above naming conventions. You may find that many software development firms have their own unique naming convention. This article should give you an an idea about naming conventions. Feel free to share some naming conventions that you have come across.

COLLECTION TYPE, SEQUENCE TYPE & INDEXABLE TYPE – Update

This is an update to the topic covered earlier. You can read about the Protocols in detail in the original article. Collection Type, Sequence Type & Indexable Type

Most of the things are the same here are some of the changes:

  1. The Indexable protocol is now not necessarily required. All the aspects of the indexable protocol now fall under the Collection Protocol
  2. The names of the protocols have changed from SequenceType & CollectionType to Sequence & Collection
  3. The keyword Generator has been renamed to Iterator. Accordingly the generate function has been renamed makeIterator function.
  4. The collection protocol now requires the implementation of the function index, this function returns the value of the next index.

The sample code below should clarify

class CustomStack
{
    var data : [Element] = [Element]()

    func push(Element newElement : Element)
    {
        data.append(newElement)
    }

    func pop() -> Element
    {
        return data.removeLast()
    }
}

//Additional Implementations - not strictly required
extension CustomStack
{
    typealias Index = Int

    var startIndex : Index
    {
        return 0
    }

    var endIndex: Index
    {
        return (data.count - 1)
    }

    subscript (position : Index) -> Element
    {
        return data[position]
    }
}

extension CustomStack : Sequence
{
    typealias Iterator = AnyIterator

    func makeIterator() -> Iterator
    {
        var index = 0
        return AnyIterator({() -> Element? in
            if index < self.data.count
            {
                let res =  self.data[index]
                index += 1
                return res
            }
            return nil
        })
    }
}

extension CustomStack : Collection
{
    typealias SubSequence = CustomStack

    subscript (bounds: Range) -> CustomStack.SubSequence
    {
        let newStack : CustomStack = CustomStack()

        for i in bounds.lowerBound...bounds.upperBound
        {
            newStack.push(Element: data[i])
        }
        return newStack
    }

    /// Returns the position immediately after the given index.
    /// - Parameter i: A valid index of the collection. `i` must be less than
    ///   `endIndex`.
    /// - Returns: The index value immediately after `i`.
    func index(after i: Int) -> Int
    {
        if i < endIndex
        {
            return i + 1
        }
        return i
    }
}

When to use Swift & when to use Objective-C?

Over the past few years I have received a number of questions with regards to Swift & Objective-C. Specifically related to the future of the 2. I will try to address those questions in the form of an FAQ.

Should I learn Swift or Objective-C?

This is a question that I get from developers new to iOS/macOS App Development. Ideally speaking, you should learn Swift. As that is going to become the main language for App development on Apple’s ecosystem. However, the reality is a little different. There are a large number of applications that are written in Objective-C. You are likely to encounter them at your workplace. You may also have to maintain, upgrade & improve those apps. In such a case, it makes sense to learn Objective-C too.

Can I mix Swift & Objective-C in the same project?

Yes! But remember that you should check for feature compatibility between the 2 languages. Adding Swift code to an Objective-C project may not be very beneficial as only those features that are compatible with Objective-C can be written in Swift.

Going the other way round is not a problem. You can read more about that here:Mixing Swift & Objective-C

Will Objective-C be deprecated in the future?

That is an interesting question. There is no formal announcement from Apple stating the Objective-C is going to be deprecated. However, one can expect more attention to be paid to Swift. That is where most of the newest techniques, tools & technologies are going to be available. Objective-C will keep running as it is as of now.

Can I mix Swift with other Programming Languages?

Swift can easily be mixed with Objective-C. If you wish to incorporate C++ or C code in your Swift Project then wrapping them in Objective-C code allows you to achieve this.

Apart from that Swift does support working with C code code. You can read about that here:Interacting with C APIs.

Swift does not provide interoperability support for any other languages as of now.

Which version of Swift should I use?

It is recommended that you use the latest available version of Swift. However, the actual version that you work on depends on many other factors like: compatibility with OS Versions, support & business related choices.

Why shouldn’t we just convert all our Objective-C code to Swift and keep things simple?

A very tempting proposition. However, practical realities prevent us from doing this. The process of converting from Objective-C to Swift is time consuming. Apart from having to convert the syntax, the code also needs to be optimised taking into account the new features that are available. This will mean extensive testing and quality assurance. Most companies will not invest their resources into this endeavour.

A better approach is to migrate to Swift gradually. Here are some ways to do this:

  1. If its a brand new product/app that you are creating, start it in Swift.
  2. Any new reusable code components that are being created should be done in Swift (they should be Objective-C compatible if you intend to use this code in Objective-C projects).
  3. If any part of a product is going to undergo heavy change, either due to a bug fix or a new feature. This is a good time to convert it into Swift.

A good example is how Apple is approaching the process of migrating to Swift. They are doing it component by component.

I have been developing apps in Objective-C for some time. I am able to create any reasonably complicated app now. If Objective-C hasn’t been deprecated then should I start making apps in Swift?

This is a choice that you have to make. It is recommended that new apps (at the very least) be made in Swift as that is the language that will undergo the maximum amount of changes & improvements in the future.

What do you suggest as a trainer?

Another question that I get very often. It depends on the situation. I would say learn both Swift & Objective-C. You can skip learning Objective-C if you are confident that you will not have to work with any projects written in that language.

If I am starting on a brand new project I would use Swift. But if its an Objective-C project I would stick to Objective-C.

Can Swift development only be done on macOS?

No! Swift development can also be done on Linux. However, iOS/macOS/tvOS/watchOS App Development can only be done on macOS through Xcode.

How should I migrate to Swift?

There are different approaches that one can use. It all depends on the situation and needs of your organisation. Here are some things that you can do:

  • Start development of brand new apps (from scratch) in Swift.
  • If you are creating a brand new library which will be used for future projects then go ahead with Swift.
  • If a major component of an existing app is going to be changed significantly then you can go ahead with Swift.

You can do all or some of the above. There may be other strategies too. You should also factor in the cost of migration from one language to another.