First Steps (5) Common pitfalls

Common pitfalls and how to avoid them.
Below I have listed the pitfalls that have caught me out most often since starting in Android development. Hopefully this short checklist of rules will help you quickly skip over basic problems...


Rule 1: CHECK THE MANIFEST!
Yes I did shout that. In the early days this caught me out countless times and still from time-to-time now. The Android manifest file is the code of your app and holds it all together. Activities must be listed in the manifest as well as the permissions you app requires.
When you add a new activity to your project you'll need to add an activity entry to the manifest. Refactor or rename an activity and your code will be nicely updated, but not your manifest. It's easy to fix, but you'll just kick yourself each time it happens, mostly because the project will happily build and it won't show itself until you get a nasty force close.


In addition you may be adding code that requires a permission. The most common is probably internet access. If you forget to add this permission to the manifest then you will see "Permission Denied" errors. If you're doing something like hitting a web service it can sometimes take a few moments to sink in where the permission problem lies and you'll kick yourself again!

Rule 2: Keep it Clean
Resource file changes are not available within your code immediately, you must clean up your project to refresh the references. For example, if you add a value to your res/values/string.xml file call 'bob', initially your code will make R.string.bob as an error. To fix this you need to clean which recompiles the resources.
From the Eclipse menu, pick Project > Clean...

This call also remove any lingering errors that are being reported but may have been resolved.

Rule 3: Don't forget your XML header and first node type in your layouts
All of your XML resource files must start with an XML version node (line 1, below) and the first node must contain an Android XML namespace attribute (line 2, below). Your resource file will not compile without these.

<?xml version="1.0" encoding="utf-8"?>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent">

Rule 4: Look out for Android.R
Sometimes when you paste or reference from another project an 'import' reference to the Andriod.R resources is added to your code. This then means that when you try to reference your own resource with R.something the API looks for a reference in the Android.R namespace and warns you it cannot be found.
Simply remove the 'imports Android.R;' line from your class. Another easy fix, but can be confusing when it happens.

Rule 5: For String comparisons use .equals
When comparing strings, use myString1.equals(myString2) rather than "==" (double equals) as this will avoid comparison problems. Use equalsIgnoreCase for case-insensitive comparisons.

Rule 6: Check for emulator internet access

Sometimes, inexplicably, the network availability is lost on my emulator. Again, this is very easy to miss and can drive you to insanity trying to determine why things have stopped working. Just keep an eye on connection status in the notification area of the emulator to avoid this.

The emulator connection can drop for no reason

Rule 7: View items missing from LinearLayout

If you create a linear layout and find that only the first view (a TextView for example) is showin, it probably means you haven't set the orientation. If the width of the first view is set to fill/match parent and the orientation is not defined then all subsequent views will be rendered off-screen to the right.

<?xml version="1.0" encoding="utf-8"?>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"><TextView
      android:text="One"
      android:layout_width="fill_parent"
      android:layout_height="fill_parent">
<!-- You won't see the following view if the orientation is horizontal or not set -->
<TextView
    android:text="Two"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent">

Rule 8: DON'T PANIC!

Yes, I shouted again. On occasion I have seen my list of errors suddenly go through the roof after only a minor change. This usually boils down to a small XML change (layout, or other resource) that resulted in some invalid mark-up and suddenly your project looks a mess. Take a deep breath, try to think what you've changed and take a look at the first error or so in the list. It may just be that you've missed a quote or an angle bracket.


So, that's my list so far. Any further suggestions are welcomed. I hope it saves someone some of the pain I went through during my first steps.