When developing a framework, or when developing as part of a team, it is a good idea to have an agreed set of coding guidelines.
I strong believe this is important so that the code is consistent, providing everyone on the team with agreed-upon understandable code. As a creative individual, it is very easy for a developer to start hacking away, with little thought or intention to the code structure, style or typography. In my opinion, this often leads to a big ball of mud.
There are those that would say that getting a project done and out-the-door with the required functionality with as little time (cost) spent is a perfectly-good approach to software development. This approach can, and does, work for many businesses today. This is most often seen in small development shops, with often a solo developer who is developing an application for a client. They may intend on eventually washing their hands of the application, so the code design doesn’t really matter. Or, they are getting paid for the time spent to maintain the application in the future, and heck, more billable time is more money at the end of the day. So, why focus on coding conventions and guidelines?
Why?
There are several reasons to have a set of agreed-upon coding conventions/guidelines:
- During the lifespan of an application, often more time is spent in the maintenance phase than in the initial development phase.
- The code of an application will most likely be touched by more than one person. This is true for development teams who will work on the same code at the same time (hopefully using source control). And, this is also true when a new developer is added to a project, or when the original author is no longer working on the project.
- When maintaining code (see #1 above), reading and having an understanding of the code is not only criticalto minimizing the time spent during maintenance, but is alsocriticalto minimizing bugs and issues created during code maintenance.
- If your code is meant to be used by other developers (think of an API or selling your code to someone), then they will need to be able to easily read and understand your code. If they are integrating with your code, they will appreciate your consistency and clarity.
What Should the Guidelines Cover?
Coding guidelines should cover topics such as:
- File and folder naming
- File and folder organization
- Indentation
- White space
- Commenting use, location and style
- Variable naming and capitalization
- Method naming and capitalization
- Class, interface and protocol naming and capitalization
- Programming principles
- Design patterns and common solutions to problems
Apple’s Coding Guidelines
Fortunately for Objective-C developers, Apple has created a complete set of coding guidelines that spell out:
- Code naming basic
- Method naming
- Naming functions
- Naming properties and data types
- Acceptable abbreviations and acronyms
Here is a quick overview of their naming conventions:
- Naming should exercise clarity over brevity.
- Naming should not include abbreviations or acronyms, unless in the list of acceptable abbreviations.
- Naming should be consistent throughout the code base.
- Private instance variables should start with an underscore
_. - Method names should be lower camel-case. They should not start with an underscore.
- Method names can start with a capitol letter if using an abbreviation, such as:
- (NSString *)PDFpath; - Classes should be named using nouns.
- Protocols should be named using the gerund (ing at the end) of a verb.
- Only use a prefix for a common set of classes. For example, all classes for particular framework should start with an abbreviated prefix: UI (UIKit), NS (foundation), CF (core foundation) or RK (restkit).
- Methods that return something, should indicate that without using “get”.
- Methods that return a boolean should use “is” prefix.
- Method arguments should indicate what the argument requires using a keyword before the argument.