Problem/Solution Documentation

When doing development you often run into problems that you have to spend a great deal of time figuring out the solutions to. Generally that’s because the problem isn’t common enough to have a lot of documentation or its so common other people don’t post about it.

These problems also have a tendency to crop back up, but after you’ve forgotten how you solved the problem. The solution is of course to write something down.

I’ve come up with a system that is serving me well. When I have one of these problems I create a new note in my Development notebook in Evernote. It immediately gets three headings added: Problem, Context, and Solution.

The Problem is what you encountered you have to find a solution to.

The Context is what environment or circumstance is the problem in. For instance is it with Magento or iOS?

The Solution is how you solved the problem.

Once I started doing this, I decided I’d start blogging my answers. Those previous Problem/Solutions can be found on my personal blog. From now on they will be here on the Reactuate Software Blog.

Variable Names – Coding Style

At Reactuate Software one of our main goals when creating software is making the code readable. Readable code makes everyone’s life easier. It is less prone to mistakes. It’s easier for new developers to learn. It’s easier for a developer to understand when they go back to code they wrote a long time ago.

Here’s how I do it. These practices were developed over decades of coding, and are heavily influenced by Objective-C/Cocoa conventions. Some may actually vary based on the language we’re coding in, but the principles apply. For example, CamelCase is the norm in Objective-C, but frowned on in Python. So if you see inTagArray below in Objective-C, that would be in_tag_array in Python.

Full Words Please

[box type=”warning”]Single letter variables are of the devil.

Never use them.[/box]

About the only place I accept a single letter variable is a simple loop. ‘for( int i=0;i<10;i++)' is pretty understandable1, but actually getting to be rare in the real world. Single letter loop variables can get confusing quickly if you have loops inside of loops.

Another exception are the special x,y,z variables when plotting points. Those are the actual names of the axis you are referencing, so go ahead and use them. Which is a also a good reason not to use X in other places.

[box type=”warning”]No abbreviations or acronyms either
They may be obvious to you today, but not so for other readers of the code. I don’t know why coder’s feel they have to save a few key strokes by making variables abbreviations, especially in the age of editors with autocompletion.[/box]

The other day I was looking at a tutorial and the writer’s sample started with something like this:

[cc lang=”objc”]NSString* rhs = @”abcd”;
NSString* lhs = @”efg”;

if ( [rhs isEqualString:lhs] )[/cc]

It’s pretty easy to understand what the code is doing, comparing two strings. But what does rhs/lhs mean? The sample code was discussing how lhs == rhs is done with string routines. Then I figure it out. They meant Right Hand Side, and Left Hand Side. OK, why not name them that? RightHandSide would be perfectly valid and more readable.

Actually I would probably have named them rightString and leftString. This tells what they do/mean, and it tells me their type. Which brings me to my first style guide.

Always Name The Variable By What It Represents

Needless to say…well I guess it’s not needless to say or I wouldn’t be writing this.

Give variables meaningful names. Later in the code you are only going to have the name when reading code.

I also like to include the type in the name, though it isn’t always needed. Like the above example, adding String to the end let’s the reader know the variable holds a string and not a number. Yeah, you could look back at the comment on the definition if you get confused, but why not make the name self documenting?

When I name my outlets for UI objects in iOS/MacOS, I name them with the type of object they are, for example usernameTextField, and passwordTextField. Because later I may see those variables, and while I know they handle text because that’s what a username is, knowing it is a text field tells me a lot more about that text. It’s a single line not multiple lines. It isn’t rich text. It’s probably editable or I’d have labeled it usernameLabel.

Windows programmers have long used Hungarian notation where the first characters or characters represent the type of the variable. I used to think this was dumb because you had to learn a new convention when you could just look at the definition. I still think having to learn a cryptic set of rules is a pain, but having the type in the name is very useful.

Meaning Can Be Relevant to Role in Code

[box type=”info”]Never use any variable for more than one thing.
Variables don’t cost you anything but keystrokes. If you want to do something else, make a new variable, don’t reuse one you think is “done”. This is asking for disaster.[/box]

Temporary Variables

Some variables don’t have a global meaning. For instance a variable that is just there to hold a value while you do something to it. If they are really, really temporary, I’ll just name it ‘temp’. But if they are only kind of temporary, meaning they stay around for more than a couple of lines, or there are more than one temporary variable, then I’ll name them based more on what they hold. tempString, or tempSortValue, etc.

Parameters

Another special naming convention I use is in and out prefixes on parameters. Parameters of a method/function/procedure always get prefixed with ‘in’. If they are being used to send some value back to the caller via reference or pointer, they get prefixed with ‘out’.

Why? Because you should never alter parameters that are passed in. In C++ you could define these as const and the compiler wouldn’t let you change them, but not in Objective-C. If you need to change something in an ‘in’ variable, make a copy. And think about what it means to make a copy.

Here’s an example method:

[cc lang=”objc”]- (void)addTagsFromArray:(NSArray*)inTagArray;
{
for (NSString* curString in inTagArray)
{
[self addTag:curString];
}
}[/cc]

The routine adds an array of strings to an object’s tag list. The parameter sent in is named inTagArray. ‘in’ because it is a parameter, ‘Tag’ because that’s what it contains, ‘Array’ because that’s its type.

Loop Variables

The addTagsFromArray method shows how to handle an enumerator variable. Prefix the variable that contains the current variable with ‘cur’. The variable probably should have been ‘curTag’, since it contains a tag, and a tag just happens to be a String. But in this case it works because in the future I may change a tag to be something other than a string, and when I do I’ll rename the variable to indicate it contains a Tag object.

Return Values

When I write a new method that is going to return something, the first code I write will look like this:

[cc lang=”objc”]- (int)someRoutine;
{
int returnInt = 0;

return returnInt;
}[/cc]

I learned this from the book Code Complete: A Practical Handbook of Software Construction, which is a great resource to learn about writing tactically defensive code.

I’m doing three things here.

1) I’m declaring a value that will hold what’s being returned. If that value isn’t set, the routine shouldn’t be returning yet. When you’ve figured out what to return, this is where it goes.

2) I’m giving the return value a useful default value. If an unset return is a error, then set the error value here. For an int, you probably want to initialize to zero just to be sure.

3) I’m actually doing the return. First this will get rid of a compiler warning that you don’t have a return value. Second, you’ll always return something, which is good, because just exiting a routine that expects a return value is undefined.

There are rare occasions when readability has to take a back seat to performance, and sometimes what the code does is just too complex to easily understand at a glance. But the readability of a variable name never impacts performance. Variable names are for the programmer, not the compiler.

Summary

  • Always give variables meaningful names.
  • Always use complete words. No abbreviations.
  • Include variable type in the name.
  • Parameter names are prefixed with ‘in’ or out ‘out’.
  • Create a variable prefixed with ‘return’ and return statement when creating a new routine.


Footnotes:

  1. Of course 10 is a “magic number” which will be the topic of another post.

5 Things You Should Always Get From A Developer

Dirty KeyboardYou know your business. You have knowledge specific to your industry. If you are like me, there are lots of times you see customers, or potential customers making the wrong choices when selecting someone to do what you do. You can’t really blame them, because they don’t know what you know. If a friend were going to buy your product or service, what advice would you give them to make sure they got the right person? (Assuming they had to buy from someone else).

Well friend, this is what I tell my friends if they want software created. These are the things an experienced developer knows make a big difference to your outcome, but are often glossed over or missed.

When you hire someone or some company, to develop software for you you have a lot on your mind. Can they do the work? Will they deliver on time? Will they deliver at all? Will they do what I want? How much will it cost?

Those are all valid things, and I’m going to talk about them in future blog posts, but first let me tell you 5 things always I want from anyone I hire to develop software for me.

Most of these things aren’t that critical when things are going well. But when disaster strikes – like the guy you’ve got writing your mission critical application get hit by a bus – these are the things that are going to make a big difference.

These things seem kind of technical and they are. You may not even understand what they mean, and that’s OK. Any developer will understand them – if they don’t you’ve got another problem. But if you have to replace your developer, for whatever reason, you can hand this information to the new guy, and he’ll be up and running in record time.

At Reactuate Software we call these things Provisions. If a requirement is what a client asks for, a provision is what we insist on giving them.

The Reactuate Software Provisions.provisions_cw

1. Access to the source code. When you hire someone to create a program for you, what you are paying for is source code. Yes deliverables will include a public release ready compiled binary/application, but unless you are never going to make any changes to that app, you need the source. You need access to that source at any time, and the best way to do that is via a source control repository.

2. Source code should be in a online, off site repository. A source code repository is a special program that keeps track of programming code and the changes made to it. A programmer can have a repository on their own machine. They can have one on a server in their office, and they can have one somewhere in the cloud. The cloud solution is what you want. This keeps the source safe not only if they get hit by a bus, but also if their office burns down. This repository should be secure and private. You the client should be able to access that repository easily and at any time. The Developer should be updating the source regularly.

3. Issue tracking. The developer should provide a bug/feature/enhancement tracking database. Bug tracking can be a challenge for any developer. Every bug report needs to be in writing, and should include steps to reproduce. Many small projects just use email for this, but that doesn’t make it easy to track the status of issues and make sure everything is handled before a release. There are many solutions that provide a web based system for doing this and most are connected to source repositories. You’ll have to decided how public you want this to be. You might want for users to be able to report bugs, or only your customer service people. Either way they should be tracked.

4. Always have a Ready to Release build of the application. Once you’ve reached version 1.0, there should always be a ready to go version of the app available. Normally this will be the master branch in the source control system. As bugs are fixed, in their own branch, they can be tested and pushed into the master. Then the master can be built and be ready to release with new bug fixes. This allows you the client to put out regular updates to your app at just about any time.

For web applications, they master branch may be the release. Any time a commit is made to the master, your web server can be updated and changes made live. This allows for the shortest time between the coding and getting it in front of users.

5. Clearly defined deliverables and processes. You should know from the beginning what your Developer is going to give you in the end. What do you need to call the project done? You also need to define how these things will be delivered. For instance, if you are receiving an iOS app, who is submitting it to iTunes Connect? Who’s responsible to provisioning?

Hopefully that will help you with your next project. If you are looking for a software developer that does all these things by default you can contact us here at Reactuate Software.