A Few Programming Practices: Writing good code
09/13/2010 § 1 Comment
Obviously that much of what I will speak about here is kind of a convention between Cocoa developers, some may not be, but certainly are details that I believe that makes the code more readable.
First of all we write Objective-C code, meaning that our parameters are named. This just happens to be one of our most valuable tools for writing readable code. Don’t be shy to come up with long names (Apple does that too), that is precisely the reason we have named parameters. Be clear.
The second important tip is to keep your code simple. You must have heard this phrase a lot, but maybe no one told you what they wanted to tell when using it 😛
I mean that you should think about using delegates to handle stuff that you are not sure about how it will work on a different context or even in the future. Note that I am not saying that you write code without knowing what it is. Instead, let me give you a real example:
Suppose that you are writing a drag’n drop photo view that can be dropped only on a certain area of the screen. What should happen if you drop that photo outside that area? The first thing that comes to my mind is to animate the photo view to it’s original position, because the operation failed. But, this photo view could be used inside a popover and maybe it is better to dismiss that popover when the dragging starts…and if you dismissed it, to where should the photo return to? Nowhere. In this case, I would add a delegate method to ask someone if I should return the photo to it’s original position or not. Got it?
Of course, you should write delegate methods when you know that it’s useful. Don’t run around creating lot’s of unneeded delegates.
Speaking about delegates and method naming, there are also some delegate conventions that I love to follow. One of them is to pass self as parameter to every delegate message. This is very cool because usually prevents you from creating instance variables (as you soon will notice if you start doing this) and gives you improved readability for free. You can read the delegate method and know exactly what is going on.
Suppose that draggable photo view we spoke about earlier. What would be a great delegate for it?
@class DraggablePhotoView;
@protocol DraggablePhotoViewDelegate<NSObject>
@optional
- (BOOL)shouldPhotoView:(DraggablePhotoView *)photoView beDroppedOnto:(id<DragablePhotoRecipient>)recipient;
- (BOOL)photoViewShouldReturnToOriginalPositionOnDropFailure:(DraggablePhotoView *)photoView;
@end
Big names right? But you know exactly what is going on without even reading the implementation code right? And Xcode auto-completes for you right? That is what I mean.
These tips can also be applied to variable names. Don’t fear writing variables with a clear name, because you spend more time reading code than writing it.
But just adding long names doesn’t really improves readability. In order to achieve that, you need to think about what name a method should have (what does it do?). If it is to complex to find a good name, probably you should split that method into two or more, because it is doing so many things that you can’t describe it briefly (and therefore your method may have just a few lines of code). So, think about the problem itself before you write any code.
To summarize variable, method and class naming:
A perfect code should be readable enough to need no documentation.
But of course, don’t hesitate to add it when you feel that it is necessary (it is very difficult to achieve perfection 😉 ).
I am not here to tell you that you should capitalize words and add initials to your classes, you can find this kind of stuff all over the internet (and if you really search for it, you will find people talking about the tips I am posting here, because this is not my invention). But pay attention to the guides that are available for what you are working with. Apple for example gives you a lot of “Best Practices” stuff in their documentation.
….
And what about boolean variables?
For sure you need them, but you probably don’t like to add a lot (like 3 or 4) to your code. Do you?
I don’t, and this is why I think it is a good idea to use Enumerations instead. Just one variable, that tells you everything.
typedef enum {
SomethingStatePossible
SomethingStateBegan,
SomethingStateCancelled,
SomethingStateFinished
} SomethingState;
SomethingState state;
Isn’t it good? It doesn’t fits to every “boolean case”, but usually prevents you from having lots of them.
And finally the BEST PRACTICE EVER
Ask someone to review your code and share thoughts with you.
This post would be much larger if I added all that I think that makes a good code, so I decided to comment about just the ones that I think is very important and not-everybody-already-follows-it.
So, if you have any tips to share (that you think I should have commented for example), post a comment and let’s discuss about them!
iOS Guy 
Nice Post. Thanks.