BlogmyQuery – BMQ

Getting into Android development can be quite a challenge, particularly if you’re new to Java or Eclipse or both. Whatever your past experience, you might feel tempted to start working away without checking that you’re making the best use of the IDE. In this article, we’ll go over a few tips, tools and resources that can maximize Eclipse’s usefulness and hopefully save you a few headaches. You might of course already be familiar with some (or all) of them and even be aware of others that we haven’t covered. If so, please do feel free to mention them.

I’ve used Eclipse for Java development on and off for a few years, having recently started learning Android casually. I’m surprised at the lack of easily digestible material online about basic aspects of Android development, such as the topic of this article. I’ve found some useful information out there in disparate locations that are not particularly easy to come across. Most of the online content is still in the official Android Developer Guide, but it has to be said that it is pretty limited in practical material.

The aim here, then, is to provide a concise overview of Android development tools specifically in Eclipse. If you’ve already started developing for Android, you will almost certainly have come across some of them, but a few might be new to you, especially if you’re learning Android casually or part time. If you’re approaching Android as a Java developer and are already accustomed to Eclipse, you’ll likely grasp this material well.

Get To Know Eclipse

Going over some features of Eclipse itself that would be useful for developing Android projects would be worthwhile. If you already know your way around Eclipse, you can probably skip these first few sections, because they’re really aimed at people who are learning to use the IDE purely for Android development. Later sections include tips on using Eclipse specifically for Android, so you might find a bit or two in there that you haven’t explored yet.

The Eclipse IDE, with the “Hello Android� project open.

Eclipse has a huge amount of flexibility for creating a working environment for your development projects. Many display options, tools and shortcuts in Eclipse enable you to interact with your projects in a way that will make sense to you directly. Having been an Eclipse user for a reasonable amount of time now, I still discover features in it that I had no idea existed and that could have saved me a lot of hassle in past projects.

Explore Perspectives

The Eclipse user interface provides a variety of ways to view the elements in any project. When you open Eclipse, depending on which “perspective� is open, you will typically see the screen divided into a number of distinct sections. In addition to the code editing area, you should see various aspects of the project represented in particular “views.�

A perspective in Eclipse is a group of views arranged to present a project in a particular way. If you open the “Window� menu, then select “Open Perspective,� you will usually see at least two options: “Debug� and “Java.� The Java perspective will likely form the basis of your Android development process; but for debugging, there is an Android-specific perspective called DDMS. Once you have set a perspective, you can still make alterations to the visible views, as well as adjust the layout by dragging the view areas around to suit yourself.

In general, when developing Android projects, some variation of the Java perspective is likely to be open, with the option of a few additional views, such as “LogCat,� where you can send and read the runtime output of your app. The Dalvik Debug Monitor Server (DDMS) perspective will likely be useful when the time comes to debug your Android applications. The tools in this perspective come as part of the Android software development kit (SDK), with Eclipse integration courtesy of the Android Developer Tools (ADT) plugin. The DDMS perspective provides a wide range of debugging tools, which we’ll cover in brief later on.

Make Use Of Views

By default, the Java perspective contains the main area to edit code and a handful of views with varying levels of usefulness for Android projects:

• Package Explorer
  This provides a hierarchical way to explore your projects, allowing you to browse and control the various elements in them through a directory structure.
• Outline
  Displays an interactive representation of the file currently open in the editor, arranged as logical code units, which can be useful for quickly jumping to a particular point in a big file.
• Problems
  Lists errors and warnings generated at the system level during the development process.
• Javadoc
  Useful if you’re creating your own documentation using Javadoc or using other language resources that have this documentation.
• Declaration
  Particularly useful if your Android projects have a lot of classes and methods. You can click on a variable or method in your code to see its outline here, and then click within the view to jump to the point where the item is declared.

You can open new views in Eclipse by selecting “Show View� in the Window menu and clicking from there. Many of the available views won’t likely be of any use to your Android project, but it is worth experimenting with them. If you open a view and decide that you don’t want to display it after all, simply close it. Adjust or move open views to different locations in Eclipse by clicking and dragging their edges or the tabbed areas at the top.

Java Views Relevant to Android Development

The ADT plugin for Eclipse includes a variety of resources for Android development within the IDE, some of which we’ll cover in the sections below. Eclipse has additional views for general Java programming, some of which naturally have a greater potential for usefulness in Android development but don’t appear by default in the Java perspective. In my experience, views that are useful for Android development include “Call Hierarchy,� “Type Hierarchy� and “Tasks.�

The Call Hierarchy view displays an interactive list of the calls for any particular method, class or variable, so you can keep track of where your code excerpts are being called from. This is particularly useful if you’re altering existing code and need a sense of what will be affected.

The Call Hierarchy view for a method in one of my projects.

The Type Hierarchy view is relevant to Java projects that involve inheritance, which basically means that it’s relevant to all Android projects. Whenever you have a class that extends another class, this is inheritance and, thus, an instance when the Type Hierarchy view can be informative. If you’re not yet familiar with inheritance in Java, taking the time to at least read up on the basics is well worth it, because the technique is key to Android programming.

The Type Hierarchy for a user interface element in an Android project.

The Tasks view is one I personally find helpful, but it really depends on how you choose to organize your projects. Think of the Tasks view as an interactive to-do list. For example, to add a task when you haven’t quite finished a particular bit of implementation but need to address something else right away, write a code comment, then right-click in the border area just to the left of the editor section, choose “Add Task,� and set your options from there. Once tasks are in a project, you can read them in the Tasks view, jumping to an individual task in your code by selecting it here. Tasks are also highlighted in the right-hand border of the editor.

The Tasks view, with a random comment in the “Hello Android� project.

Android Debugging Views

The DDMS perspective contains several views for Android development and debugging. When you first open the perspective, you might feel a little overwhelmed, particularly because the views are all presented side by side in a rather convoluted arrangement. Chances are that once you learn the purpose of one, you’ll decide whether it’s relevant to your project; for a basic project, many of them will not be.

If you feel that closing some views would make the interface an easier environment to work in, then go ahead and close them; you can always open them again later. Starting simple is sometimes best, and then adding elements over time as they become relevant. In the early stages, your Android project is not likely to be complex anyway.

Let’s go through each DDMS view in Eclipse, with a brief note on its purpose and use. The information is tailored to each view and so is pretty varied, but includes device, memory and process management.

The Devices view provides an overview of your running AVD emulators together with processes in operation, and it is the starting point for exploring your projects for the purpose of debugging. This view presents shortcuts to some debugging operations, so you can select your app’s processes from here to see the other debugging operations in action. In most cases, you can view information in the other DDMS views by selecting a running process in the Devices view while your app is running in an emulator, then using the buttons at the top of the view to capture debugging information. When you do this, you’ll see some of the other views being populated with data.

The Devices view, with a process selected for debugging.

The Allocation Tracker view is particularly useful for apps that have significant demands on performance. This view provides insight into how the Dalvik Garbage Collector is managing memory for your app. If you’re not familiar with garbage collection in Java, you might want to read up on it, as well as familiarize yourself with basic principles of efficiency in Java programming, such as variable scope.

The Allocation Tracker view in the DDMS perspective.

The Emulator Control view enables you to emulate specific network contexts when testing your apps, allowing you to see how they function with varying constraints on speed, latency and network connectivity. A vital tool if your app depends on such external connections.

The Emulator Control view with telephony settings.

The File Explorer view enables you to access and control the device’s file system (not the file system in your application’s structure as with the Package Explorer view). Using this, you can copy files to and from the device’s storage system; for example, in the case of an app storing data on the user’s SD card.

Looking at the SD card directory on a virtual device using the File Explorer view.

The Heap view is another tool for analyzing and improving memory management in your app. You can manually control the Garbage Collector from this view. If you are unclear on how the constructs of your Java code relate to heap memory, this is another area you might want to read up on.

The Heap view for a running app.

The Threads view enables you to access information about the threads running in your application. If you are unfamiliar with the concept of threads, then this view won’t likely be of use to you. Typically, an Android application runs in a single process on a device, but if you implement a deeper level of control over your app’s processing at the level of threads, then this view will be relevant.

The Threads view for a particular running process.

The LogCat view is useful for most Android apps, regardless of their complexity. A variety of messages are automatically outputted here when you run your app, but you can optionally use the view as your own custom log. You can create log messages in various categories, including “Debug,� “Info,� “Warning,� “Error� and “Verbose,� which is typically used for low-priority information such as development trace statements. In the LogCat view, you can then filter the messages in order to quickly scroll to those you’re interested in. The messages are also color-coded, making them a little easier to absorb.

The LogCat view as a virtual Android device starts up.

A DDMS perspective view can optionally be added individually to the Java perspective if you find it useful for development as well as debugging. Eclipse is designed to enable you to interact with the project’s elements any way you like, so don’t be afraid to experiment with the interface.

Exploit The Design Tools

The design tools in the ADT have undergone major improvements in recent releases, so if you’ve been disappointed by them in the past and perhaps opted for other tools to design your Android apps, having another look at them now is well worth it.

In the Graphical Layout view, you can view your designs with various settings for device software, hardware as well as orientation. The current version generally gives a greatly improved level of control over widgets, views and rendering than most previous versions. You can manage user-interface elements here using the graphical interface, rather than having to implement every aspect of your design in XML code.

The graphical view of an app’s XML layout.

Design and Graphical Utilities

The ADT plugin update of June 2011 introduced a variety of visual refactoring utilities. While your XML layout files are open in the editor, you can browse the options in Eclipse’s Refactoring menu for Android, choosing from various labor-saving tools such as “Extract Style,� which provides a shorthand method of copying style attributes for reuse.

The Resource Explorer is a handy interactive way to explore your application’s resources without the hassle of searching the file structure in the “res� folder via the Package Explorer. Although not exclusively for design purposes, the tool is useful for checking what design resources are in your application’s structure. Depending on the app, your Resources directory might also contain menu, array, string and value items.

The Resources Explorer showing the Resources directory for an app.

On the subject of resources, the Resources interface for any XML files in your app enables you to manage such data graphically, if you prefer not to handle the XML code manually. This can be an effective way to manage both elements and attributes for your application’s XML data.

A graphical view of the XML file for arrays in an app.

Various visual interaction tools for XML resources have gradually been added and improved in the ADT plugin. For example, the Manifest file can also be viewed graphically when you want to control the tags in it, including “Permissions,� “Application� and “Instrumentation.�

An application’s Manifest file, presented graphically.

Set Your Android Preferences

The “Eclipse Window� menu provides access to the Preferences settings for the environment as a whole, with a dedicated section for Android. You may have used this when you first installed the SDK but might not have been in there since then. It’s worth having a look through the options and experimenting with them to create the environment you want.

In the Android section, the “Build� settings include your saved edits to the project’s files, and they also point Eclipse to your keystore for signing the application. The LogCat section lets you set properties for appearance and behavior in the LogCat view. Other options include choosing properties for the DDMS, the code editors and the launch process for the emulator.

Use The Android Run Configuration Options

When you launch your Android project using the Run Configurations menu, you can choose from a range of additional options to suit the functionality of your app. With your Android project selected, choose the “Target� tab to see these options. The first section covers the more general launch parameters for the emulator, including control over speed and latency on the device. This feature is useful if your app depends on a network connection and you want to see how it functions with limited connectivity.

Emulator Command-Line Options

The “Target� tab also allows you to enter command-line options for the emulator that launches your app. Using these, you can tailor the appearance, properties and behavior of the emulator as it launches your app. A lot of options are here for various aspects of the device, including the following properties:

• UI
  Includes scaling the display window and setting the DPI.
• Disk image
  Includes the device’s SD card and cache memory.
• Media
  Covers audio and radio properties.
• Debugging
  Enables and disables specific debug tags.
• Network
  In addition to network speed and latency, you can specify DNS and proxy servers.
• System
  Includes slowing down the device CPU and setting the time zone.

For a full list, see the Developer Guide.

Choose Useful AVD Configurations

When you create virtual devices in Eclipse using the Android SDK and AVD Manager, through the “Window� menu you can choose various settings, including API versions and hardware configurations, such as the size of the SD card and screen, plus optional hardware components. The sheer range of options can leave you wondering where to start, but the feature at least gives you some idea of how your apps will look and function on various devices.

Entering the details for a new AVD.

To create a virtual device, select “New,� enter a name and choose “Options.� You can edit your devices later if necessary. To start an AVD running, select it in the SDK and AVD Manager and click “Start.�

Choosing from a variety of AVDs to start running.

Some developers prefer configuration options that match the range of Android devices currently in use, which obviously vary widely, with multiple phone sizes and types, not to mention tablets. There is no dedicated resource for finding this data, but a number of websites list these configuration details periodically, so you can do a quick Web search when testing an app for release to find the most current information.

It must be said that there is a real limit in value to using actual device settings, because the emulator is merely a guide: it doesn’t replicate the look and feel of different devices with any authenticity. These limitations are especially pertinent when you consider the third parties involved, such as HTC’s Sense interface, which will substantially alter your application’s UI. This is why testing on actual devices is also important, but that’s another topic. The range of devices running Android will obviously continue to expand, so the feasibility of covering a significant chunk of them becomes more and more remote.

Rather than focusing on actual devices in use, another way to approach the AVD configuration settings while you’re in Eclipse (i.e. when you’re still developing rather than testing) is to simply try to cover a range of settings and to explore particular hardware and software configurations that could affect your app’s functionality. Visually speaking, it goes without saying that a relative rather than fixed design will cope better with various screen sizes.

Get And Keep Yourself Acquainted With Developer Resources

As you’re by now aware, if you weren’t already, the Android Developer Tools plugin is what allows you to develop, run, test and debug Android applications in Eclipse, together with the software development kit. Like Eclipse itself, both the SDK and ADT plugins offer many tools, many of which you could very easily remain unaware of and only a few of which we have touched on in this article.

The Android development resources undergo regular updates. You might be one of those people who are always on the ball, but if you’re anything like me, you’ll rarely find the time to keep abreast of these developments, especially if (like me) Android development is not your full-time job.

The Android Developer Guide lists the various tools in the SDK, many of which you will not need to access directly, because the ADT plugin and Eclipse will handle interaction with them. But it’s worth browsing the list fairly regularly, just to be aware of the tools available. Even if you’re only getting into Android casually, these utilities can make an enormous difference to how productive and enjoyable your app’s experience is. The Android Developers Blog is another good source to keep abreast of developments.

The ADT plugin itself comes with a wealth of features and is regularly updated. The Android SDK Guide also has a page on the plugin, outlining versions and features; again, well worth checking out regularly, because there may be significant updates. Checking for updates in Eclipse through the “Help� menu is another good habit.

Android apps are, of course, extremely varied, so the utility of any given development tool is necessarily relative. Keeping a eye on updates to resources needn’t take up much time, because in many cases the updates will be irrelevant to you. But discovering the ones that are relevant could seriously improve your Android development efforts.

Following Best Practices

If you’re interested in developing a best-practices approach to managing and documenting your apps, check out Apache Maven, which uses the project object model (POM). If you’ve already used Maven for Java development in Eclipse, the Android plugin and Integration tools will enable you to adopt the same development practices for your Android app. You can learn more about Maven on the Apache website, and you can learn about getting started with it for Android on the Sonatype website.

Other Resources

• “Android Development Tutorial,â€� Lars Vogel
• “SDK Tools,â€� Android Developer Guide
• “Using DDMS,â€� Android Developer Guide
• “ADT Plugin for Eclipse,â€� Android Developer Guide
• “Introduction to Android Development Using Eclipse and Android Widgets,â€� IBM developerWorks
• “Eclipse Shortcuts,â€� Lars Vogel
• “Eclipse Documentation,â€� Eclipse Foundation
• “Eclipse IDE Tutorial,â€� Lars Vogel
• “Develop Android Applications With Eclipse,â€� IBM developerWorks
• “Eclipse Tips and Customization,â€� University of Tennessee
• “Ten Tips for Android Application Development,â€� Zigurd Mednieks

Related Articles

• “Android GUI PSD Vector Kit,â€� Smashing Magazine
• “Designing For Android,â€� Dan McKenzie
• “Get Started Developing for Android with Eclipse,â€� Chris Blunt
• “Get Started Developing For Android With Eclipse, Reloaded,â€� Chris Blunt

(al)

© Sue Smith for Smashing Magazine, 2011.

Working with code that was created by some other person or organization is routine for developers, but it can be one of the most demanding activities, particularly if you’re still learning. From using code libraries to working on a team of developers, there are bound to be times when you need to get to grips with code written by someone other than yourself.

Whether you’re a software developer or a Web designer who does a bit of coding from time to time, your work routine might sometimes be isolated, but your work typically is not. When you use an external resource or work on an existing system, you see that your work exists in the context of other technologies and, yes, other people.

For developers, the nightmare of other people’s code is one of the most frustrating aspects of the job. But I believe this needn’t be the case. If you can get into a few “healthy� habits and learn to see unfamiliar code as an opportunity, then your working day will be less stressful and your own code-writing skills will ultimately improve. Don’t worry: this isn’t a self-help presentation, and no mantras will be required.

In this article, we’ll go through a few tips and techniques (with particular reference to JavaScript and a little PHP) that can make working with other people’s code less nightmarish and more productive. If you come from a programming background, you might already indulge in many of these activities already. But who knows? Maybe you haven’t come across some of them yet. If you’re anything like me, you pick these things up in a haphazard, random sort of way. If you come from a design background, some of the tips might well be new to you.

Steering clear of the “Should Web Designers Know How To Code?� debate, this article is written to be helpful to people who are primarily designers but have chosen to get more involved in coding, as well as people who are primarily developers but are just getting started.

A Brief(-ish) Aside On Development Patterns

For developers who come from more of a design background, seeing the value in some of the techniques that more seasoned programmers use can be difficult. Let’s briefly look at some of these, and don’t worry if you don’t know much about programming (and don’t really care to), this is really general stuff that will more than likely prove useful. If you’re an experienced programmer, this section will likely be less relevant to you.

When you go about creating an application, whether for the desktop or the Web, you have a number of choices: not just in technologies, but in how you use them. Generally speaking, the result is a load of code that is executed to produce the required functionality and appearance. However, various options, techniques and patterns are involved in organizing and designing this code to make it carry out the required tasks.

Development patterns are used to split up the various tasks involved in creating an application. (Image: Jean-Marie Favre, part of UML diagram representing LinkedIn’s social networking system.)

Organized Code

Development patterns represent different approaches to building code to implement specified functionality. In many cases, they involve grouping sections of code and assigning these well-defined sets of responsibilities (and data).

One of the most intuitive development models of this kind is object-oriented, in which tasks are distributed between objects (with class declarations that define how objects should behave). For example, you could have an object in a payroll system that is responsible for handling wage calculations, another for processing payments and so on. Code that is external to an object should be able to use it without having to get involved in the details of what’s going on inside it.

The idea of separating code into sections, with clearly defined roles and interfaces, is common to the wide variety of programming languages and development patterns in use; for example, model-view-controller architecture, and programming paradigms used with language types such as declarative and imperative. Object-oriented programming is one of the many styles of structured programming.

Say you were writing code for a payroll system and wanted to find out how much tax an employee has to pay. The code that handles wage calculations could contain a function written in this form (pseudo-code):

number getTaxAmount(number topLine)

This means that external code can call the getTaxAmount function, passing the employee’s total wage figure (topLine) as a parameter and getting the amount of tax returned as a number. How getTaxAmount works out the amount of tax owed is irrelevant from the point of view of the “customerâ€� code. All it needs to know is:

• What the function is called,
• What the parameters are,
• What it returns, and
• What its purpose is (which would hopefully be outlined in an informative comment, although this doesn’t always happen.)

If this isn’t making much sense to you, don’t worry. Having these concepts in mind as you work with code will eventually pay off. It’s an area where learning the theory before the practice can sometimes be helpful for beginners.

Interfaces

Let’s use a car analogy to illustrate this. When you learn to drive a car, you learn what the controls are, how to access and use them, and what their general purpose is. For example, you know that pressing the accelerator generally makes the car speed up. But you don’t need to know how the accelerator makes the car speed up in order to effectively use the car.

You don’t have to know how it works, as long as you know how to achieve the desired result. (Image: Vincent X)

Looking at both the tax code example and the car analogy, we can say that the reason that these functions are usable is that, from an external perspective, the interface is clear. The interface is the point of access for the user: the controls in the case of the car, and the function outline (or signature) in the case of the payroll system. You can make use of the functionality of a chunk of code as long as you understand how to access its interface. This is a basic principle in many of the development patterns you’ll come across when reading code, both server-side with languages such as PHP and ASP, and client-side with languages such as JavaScript.

So, when developers work on substantial applications, they can usually make use of code written by someone else with relative ease, so long as the interface for the code is well defined (and, ideally, commented). Again, all they need to know is what it does at an abstract, generalized level, what inputs it takes (for example, the parameters) and what it returns.

What Does This Have to Do With Anything?

Okay, let’s see how this applies to working with other people’s code. However a piece of code has been developed, when you’re working with it, chances are you will only really need to understand certain elements in order to make good use of it. Bearing the development concepts in mind, you can focus your reading of the code on those few relevant areas. Learn to see code in terms of the visible interfaces (for example, function outlines, variables that are particularly visible or persistent, and class declarations, if applicable), and don’t waste time looking into their details unless you have to.

The rest of this article runs through some of the key skills involved in reading code.

Software developers working on big applications typically program on a team, and these skills are picked up naturally. When you code on a more casual basis, you can still pick up the skills, but you may just need to consciously focus on them at first. The more experience you gain, the more automatic these practices become.

If you’ve ever used a code library (jQuery, for example, or another JavaScript resource) and have called on it on one of your Web pages, then you’ve accessed its functionality in much the same way as what’s outlined above. You’ve called on it through a defined interface; in this case, whatever code you included in the HTML to use it, even if just a link to a script in the header of the page.

Some Useful Habits

Before we get to specific tips, let’s go over some general habits that will help when you try to make sense of an external library or other code.

Be a Reader

Get into the habit of reading other people’s code, even when you don’t have to. Life’s too short, you say? Give it a try anyway; it’s less of a punishment than you may think! If you see some functionality on a website that fascinates you, look at the code if it’s visible.

Taking a peek at the source code on the jQuery Thickbox page.

If you’re new to programming, most of the code you look at won’t make much sense at first, but you might be surprised by how your brain soaks it up. The more code you look at, the more attuned you become to processing it visually. Few professional writers would feel equipped to do their job if they didn’t spend time reading the work of other writers. Why is coding any different?

Browser tools like Firebug are really useful here, because they let you hone in on exactly the bits of code that you’re interested in, ignoring the rest. If you work with, or are interested in working with, certain technologies, focus on them. Most websites are made up of many different elements, so don’t waste time reading stuff you’re unlikely to use. If you’re only interested in client-side scripts, just look at those. For server-side code, there are many freely downloadable scripts you can look at.

Firebug enables you to view the mark-up of each element on a Web page, in this case the BBC News page.

Learn a Bit More Than You Really Need To

As you start gaining development skills, particularly if you’ve mainly been a designer, you will typically use only small isolated excerpts of code at any one time. So, you may not become aware of the larger development concepts at work in the language. Having a casual look at the structure of an application that’s larger than what you’re used to is a great way to acquaint yourself with these patterns.

On a similar note, it’s also worth finding out, at least in theory, about the types of development models that a language is used with. It may seem that higher-level concepts are not relevant to smaller tasks, but being aware of them is useful no matter how small or big your projects are. As time passes, you may find yourself working on bigger systems anyway.

A look at Smashing Magazine’s website DOM, an interactive way to explore how a website’s various elements relate to each other.

I know that spending time reading code voluntarily may be hard to justify when you’re up against a deadline, trying to get a decent hourly rate, perhaps pay the rent and eat once in a while. But the habit really will save you time and stress down the line. You have to spend only a couple of minutes here and there to benefit from it.

See Through Someone Else’s Eyes

Any development project is a problem-solving exercise. When you approach your own projects, you inevitably view them from your own angle. Moreover, programming is a linguistic activity, not unlike natural language, and there are typically many ways to express the same thing.

The downside to this is that another person’s code can seem impenetrable, because it’s specific to that individual’s point of view. The upside is that looking at how someone else has solved a problem invariably opens your mind to new possibilities. As with natural language, the fact that we all have different perspectives does not prevent us from being able to communicate, because we have a shared discourse that is understood.

Observe the ways in which code solves problems, particularly when the approach is unfamiliar to you, and especially when the code achieves functionality that you have attempted yourself. Consider how you might have approached the task, and in doing so learn something about how your brain breaks up the tasks involved in addressing coding problems. If nothing else, you might pick up a few tricks and time-saving bits of syntax.

Tips For Working With External Libraries And Other Code

If you’ve ever sat down to use a code library and found yourself struggling to understand it well enough to make good use of it, here are a few tips to help.

Examine the Evidence

Your first point of access to a code library should generally be the documentation and comments that come with it. I say “should� because as we all know they are sometimes lacking. But it’s always worth a look, and well-documented code makes a huge difference.

/* Here is an informative comment explaining the
*  function that the code appears before, indicating,
*  its logic, purpose, parameters and anything returned.
*/
function greatFunction(someInput)
{
 //What's happening and why
 var someElement = document.getElementById(someInput);

 //and so on…
}

Don’t take comments as gospel. Programmers are only human (insert your favorite joke here), and comments often get out of sync with code, especially when changes are made and the comments are not updated.

Stick to the Path

Don’t try to read code linearly as it appears in scripts. Read it in the order of execution, starting from obvious entry points. If a library provides instructions on how to carry out certain tasks, for example, start from the function calls that are specified, and work through what happens from there.

Typically with a JavaScript or PHP library, you’ll be adding some function call or link to your HTML or server-side script. So, in the first instance, look for the origins of any such calls in the source code. Again, browser tools and IDEs can be really helpful here. Follow the train of logic from your entry point through to any other functions that are being called in turn. Take your time, and build a picture.

Let’s work through an example: the jQuery plug-in for SuperSleight for handling PNG transparency in IE6. To use this plug-in, you link to the script in the header of the page and add the following function call in your page’s script:

$('#content').supersleight();

To see what happens when this function is executed, look in the supersleight.js script for the function being called (supersleight) and see what happens in there. You’ll see that it contains further function calls and processing, some of which in turn refer to the jQuery script itself. Here is the start of the function:

jQuery.fn.supersleight = function(settings) {
 settings = jQuery.extend({
 imgs: true,
 backgrounds: true,
 shim: 'x.gif',
 apply_positioning: true
 }, settings);

 return this.each(function(){
 //…

Naturally, you can look up the details of the internal function calls if you wish, although you’ll find that the jQuery script is a little more difficult to read!

The point is that if you want to make sense of code without tearing your hair out, you need to read it in the order in which it will be processed. With Firebug, you can speed up the process using the “DOM� and “Script� tabs. Many of the other browser plug-ins for Web development, such as Web Developer and Web Inspector, have similar functions. For server-side code, an IDE serves this function.

Give Yourself Some Clues

If the code you’re working with has a long complex flow of execution, then adding trace statements can be useful. Trace statements are a way to find out what is happening at particular points in the logic of a program. An example of a trace statement would be writing out the value of a variable at some point in the execution, perhaps for an alert dialog in JavaScript code, as in this example:

function someFunction(aParameter)
{
 alert("parameter value: "+aParameter);
 //other processing…
}

You can use trace statements to check variable values (as above), to test whether functions are being called, or for anything else you find helpful. Adding trace statements at key points in a piece of code and then running the code can give you a good sense of the functionality at work.

If you add a trace statement to a function that you believe is being called, and then the trace is not outputted, this is an indicator that something has gone wrong at some point in the code before the trace statement. In this case, you can move the trace statement to an earlier point of execution and see if it runs there, which might give you a better idea of where the code is breaking down. For example, let’s say you have the following function being called on a page:

function someFunction(aParameter)
{
 document.getElementById("thing").style.color="#330000";
 alert("parameter value: "+aParameter);
 //other processing…
}

If you test the page and the alert dialog does not appear, then something went wrong before it was called. If you move the alert call to one line earlier in the script (i.e. swap lines 3 and 4), and it does appear, then you know something is wrong with the line you just moved it in front of. If the alert still does not appear, then chances are the function is not being called and you need to have another look at wherever the call originates.

This is a simple example, but the practice of using trace statements is useful even if you’re not working with much programming code. The alert function is obviously intrusive at times, so an alternative to consider is the console.log() function, which you can use to send messages to Firebug. A number of other advanced debugging tools for JavaScript are illustrated in “JavaScript Debugging for Beginners,� by Webmonkey.

Isolate Trouble Spots

If any sections of code are particularly baffling, copy them into a separate script and run them from there. Experiment with the code in this second file to see if you can get an idea of what’s going on.

Consider the someFunction function above. If you were having trouble getting to grips with it, you could copy it into a new JavaScript file, add a link to the new file in your page’s header, and then explicitly call the function in the HTML, as in this example:

Hover to test

In this case, you know the function is being called when you hover over the link, and you can control the parameter to see how it functions.

Remember, you don’t need to understand every detail of a script in order to get good use out of it, so take the time to do it only if it’s really necessary. Don’t worry about utility functions that have little bearing on the code you’re interested in.

Consider the Context

Whenever you try to process code mentally, take an approach that is appropriate to the platform and context. If you have a general idea of what the code is for, keep this in mind as you read it, because it will continually provide clues to the logic at work.

Familiarize yourself with the programming and naming conventions of the language in question. Most languages have standards and conventions for naming variables, files, classes, functions and whatever else they use. Grasping these makes reading the code far easier.

There’s no guarantee that the other programmer will have adhered to these recommendation, but for many of the most widely used code libraries, they will have. Some programmers have their own rules for naming code elements, which can bring consistency even if it isn’t the standard. Naturally, it helps if the names are meaningful.

Here are a few conventions. In JavaScript, names for variables and functions typically use CamelCase:

//variable
var myFirstName

//function
function doSomeAction

//as in Java, class names often start uppercase
function MyClass

In PHP, you may come across the following conventions (the underscore is also common in names of SQL database tables and columns):

//variable
$my_first_name

//function
function doSomeAction

//class
class My_Class

You’ll come across many more conventions in the different languages, and the extent to which programmers adhere to them varies greatly. But hey, if the Internet wasn’t a complete mess, so many fantastic things wouldn’t have come of it.

Step Back

When you read a section of code, you really want a sense of the overall structure. For this reason, it can be useful to step back, literally, by zooming out from the text. Many experienced developers swear by this technique, and all you need to do is open the code in an editor with zoom controls and then zoom out until it’s really small. Don’t worry if you can’t read the details; you’re aiming for an overview.

The more programming code you read (as opposed to mark-up), the more you’ll get into the habit of seeing the structures, shapes and patterns at work. For example, as a non-programmer, you would read a JavaScript file like a natural language: starting at the top, focusing initially on the first few lines, which perhaps contain a list of variable names and other details that are not generally significant. If you read the same file from a coder’s perspective, you’d initially see the functions, loops, conditionals, etc., and the code’s defining structures.

Unlike with a natural language, you can grasp some level of meaning in an excerpt of code by looking at these larger structures. With natural language, meaning is contained primarily at the level of words and sentences. So, you need to make a slight mental adjustment when reading code.

Look at this example PHP code:

$first_name="John";
$last_name="Smith";
$age=11;
function doSomethingPointless()
{
 $count=0;
 while($count<$age)
 {
  echo $first_name." ".$last_name." ";
  $count++;
 }
}

If someone who is totally unfamiliar with code saw this, the first thing they would likely focus on is the list of variables at the top. For someone more accustomed to working with code, they would notice the structure (i.e. the function with a loop inside it).

Focus

Bearing in mind the development concepts outlined above, focus your reading on those areas that are most likely to be relevant to you. Look at the level of files, classes, functions, variables and obvious entry points, as illustrated in the “Stick to the Path� section above. You can make use of an external library even by ignoring most of it.

Take a Snapshot

If the code you’re working with is for a big application and you need a good grasp of its overall structure, try scribbling down an impression of it, either textually or as a rough diagram. The act of sketching the application’s structure is a good way to impress it on your mind so that it persists when you get to working with the code.

A sketch of an application or code elements could involve writing the names of classes, files, functions or variables, and illustrating the relationships between them with connecting lines. This is most likely to be useful if you’ve been working with code for a while. (See the LinkedIn UML-class diagram near the top of this article for inspiration on this.)

Look Away Now

Sometimes you need a break from staring at code to give your brain a chance to make sense of it. There will almost certainly be times when you feel you’re getting nowhere. I often find that when I take a break and come back, I’ve actually understood more than I thought.

Just in Case

This one may seem obvious, but if you’re making changes to code, keep copies of the original for reference. Losing track of what you’ve added and what was already there is a recipe for stress.

Advanced Tools

For more advanced programmers, a number of software tools can help when you’re trying to make sense of a big application. Naturally, developing your project in an integrated development environment (IDE) such as Eclipse or NetBeans helps, because it makes the code more easily navigable by highlighting various types of relationship between elements.

One of my Android projects open in the Java browsing view in Eclipse looking at a method’s call hierarchy.

Additional tools for reading code employ different approaches and are designed to suit different languages, but in most cases they use some sort of visualization technique to help you wrap your head around it.

Here are a few related resources:

• Grok2: Source Code Comprehension Tools
  A rundown of many source-code reading tools.
• University of British Columbia: Source Code Comprehension Tools
  An overview and analysis of code reading tools.
• Source Insight Program Editor and Analyzer
  Project-oriented program code editor and code browser for C, C++, C#, Java and more.
• AspectBrowser for Eclipse
  A visualization tool for Eclipse.
• Cscope
  A developer’s tool for browsing source code.

Don’t Let It End There

It’s easy to see working with other people’s code as a necessary evil, but I genuinely believe that it’s a valuable exercise in and of itself. When you work on Web projects, particularly as a freelancer, you often end up working in a vacuum, which is not always good for your professional development. Exposing yourself to new code (rather than to passers-by when you finally lose it!) is a great way to absorb good practices and varied perspectives.

Ultimately, the skills you learn from working with other people’s code should feed back into your own code-writing habits. Few of us have been spared the experience of staring at a piece of code we wrote ourselves only a few short days, hours or even minutes before and wondering what we were thinking. If you think like both a reader and a writer, you will ultimately create something that is better structured, more reliable and that you’d be happy for other developers to look at.

Go on. It’s fun. Honest! Embrace your inherent geekery, and develop an unquenchable love for code.

Other Resources

Some related material on reading code and working with other people’s code in general:

• “The P.G. Wodehouse Method of Refactoring,â€� Basildon Coder
  Exploring the trials and tribulations of working with legacy code.
• “Code Reading: The Open Source Perspective,â€� Spinellis
  A seminal text on code reading.
• “Why I Love Reading Other People’s Code and You Should Too,â€� Skorks
  A celebration of code reading, with helpful tips.
• “How to Read Other People’s Code, and Why,â€� Design by Gravity
  Overview of the key principles of reading code.
• “Tips to Read Other People’s Code,â€� Carlos Oliveira
  An accessible list of code-reading tips.
• “Tips for Reading Code,â€� Cunningham & Cunningham
  Another rundown of code-reading principles.
• “Hell Is Other People’s Code,â€� Exodus Development
  A fun rant about the downside.

Material related to other topics touched on in this article:

• “Introduction to OMG’s Unified Modeling Languageâ€�
  An accessible introduction to UML.
• “Design Patterns,â€� SourceMaking
  A very readable overview and analysis of design patterns.
• “Programming Paradigm,â€� Wikipedia
  An introduction to programming paradigms.

Related Articles

• jQuery and JavaScript Coding: Examples and Best Practices
  A rundown of guiding principles and practices for both tools.
• What Is the Worst Design or Programming Mistake You’ve Ever Made?
  Yet more proof that learning to program is primarily about learning to find the mistakes you’ve made.
• Getting Started With Ruby on Rails
  While specifically about Ruby On Rails, this article covers general Web application development concepts.
• PHP: What You Need to Know to Play With the Web
  A great first guide to using PHP.
• YQL: Using Web Content for Non-Programmers
  Tips on using Web content that are very accessible to those without development experience.

(al)

© Sue Smith for Smashing Magazine, 2011. | Permalink | Post a comment | Smashing Shop | Smashing Network | About Us
Post tags: Coding, communication, libraries