Thinking Through Indentation and IDE Automation

I’ve been asked a number of times about code indentation in my books by publishers, editors, and readers alike, so I thought it might be a good idea to talk about the matter in a blog post. It’s important to indent your code to help make the code more readable—to help make the flow of your code easier to see. Each indentation represents another code level. The application is at one level, classes at another, methods within the class at another, loops within a method at still another, and so on. By viewing the various levels of code within an application, you see an outline of application functionality and can better understand how each application element works. Because indentation is so important to the understanding of code, I spend considerable time working through indentation in my books so that you can better understand the examples I present.

Indentation is there for the developer to use as an aid to understanding. A few early computer languages, such as COBOL, were positional and depended on coding elements appearing in certain positions on each line. Most languages today don’t require that you use any sort of indentation. In fact, more than a few languages would let you write the entire application on a single line without any indentation at all (as long as you supplied a space between statements and expressions as needed). The compiler doesn’t care whether you indent using spaces or tabs, whether there are three or four spaces per indent, or whether you provide an indent for continued lines. The fact is that all of these characteristics are controlled by the developer to meet the developer’s needs.

Modern IDEs make it easy to indent your code as needed by performing the task automatically in some cases. For example, given an example of a Java method, you could begin by typing:

public void MyProc()
{

The moment you press Enter after the curly bracket (}), most IDEs will add an indented line and a closing curly bracket. Your cursor will end up on the indented line, ready for you to type a statement. You see something like this in your IDE:

public void MyProc()
{
 
}

The developer hasn’t done anything so far to provide indentations for the code, yet the code is already indented. Let’s say you create a variable like this:

boolean MyVar = true;

You then type a statement like this:

if (MyVar == true)

It’s at this point where some IDEs continue to provide an automatic indent and others don’t. For example, if I press Enter at the end of this line in Eclipse, the IDE automatically indents the next line for me. However, when I’m working with CodeBlocks, pressing Enter leaves the code at the same indention level as before. Neither approach is wrong or right—simply different. If I were to add a curly bracket on the next line to hold multiple lines of code within a block, CodeBlocks will already have the cursor in the right position and Eclipse will have to outdent the curly bracket to position it correctly.

Let’s say that this if statement has just one line of code following it, so I don’t use a curly bracket. When working with Eclipse, the cursor is already at the correct position and I simply type the next statement. However, when working with CodeBlocks, I must now press Tab in order to indent the line of code to show that this line (and only this line) is associated with the if statement. In this case, the example simply outputs a statement telling the value of MyVar like this.

System.out.println("MyVar == true");

Pressing Enter automatically outdents the line when using Eclipse because the next statement is automatically at the same level as the if statement. However, when working with CodeBlocks, I must press the Backspace to outdent the line manually. The resulting method could end up looking like this:

void MyProc()
{
    boolean MyVar = true;
    if (MyVar == true)
        System.out.println("MyVar == true");
     
}

Of course, a good developer will add some comments to this code as a reminder of what task the code performs and why the developer chose this particular technique to perform the task. The point of this post is that indentation is an essential part of working with most languages in order to make the resulting application easier to understand.

A final thought on IDEs is that most of them make it possible to configure the editor to indent or not indent to meet the requirements of your organization or personal tasks. IDEs commonly allow the use of tabs or spaces for indents (spaces are better when you want to write documentation). You can also choose the right amount of indentation (three spaces is optimal for books where space is limited). Let me know your thoughts on indentation and how you use it at John@JohnMuellerBooks.com.

 

Creating Useful Comments

A major problem with most applications today is that they lack useful comments. It’s impossible for anyone to truly understand how an application works unless the developer provides comments at the time the code is written. In fact, this issue extends to the developer. A month after someone writes an application, it’s possible to forget the important details about it. In fact, for some of us, the interval between writing and forgetting is even shorter. Writing good comments is a main topic in C# Design and Development as part of Chapter 13, but I make the topic part of every application development book I write. Despite my best efforts and those of many other authors, many online examples lack any comments whatsoever, making them nearly useless to anyone who lacks time to run the application through a debugger to discover how it works.

Good application code comments help developers of all stripes in a number of ways. As a minimum, the comments you provide as part of your application code provides these benefits.

 

  • Debugging: It’s easier to debug an application that has good comments because the comments help the person performing the debugging understand how the developer envisioned the application working.
  • Updating: Anyone who has tried to update an application that lacks comments knows the pain of trying to figure out the best way to do it. Often, an update introduces new bugs because the person performing the update doesn’t understand how to interact with the original code.
  • Documentation: Modern IDEs often provide a means of automatically generating application documentation based on the developer comments. Good comments significantly reduce the work required to create documentation and sometimes eliminate it altogether.
  • Technique Description: You get a brainstorm in the middle of the night and try it in your code the next day. It works! Comments help you preserve the brainstorm that you won’t get back later no matter how hard you try. The technique you use today could also solve problems in future applications, but the technique may become unavailable unless you document it.
  • Problem Resolution: Code often takes a circuitous route to accomplish a task because the direct path will result in failure. Unless you document your reasons for using a less direct route, an update could cause problems by removing the safeguards you’ve provided.
  • Performance Tuning: Good comments help anyone tuning the application understand where performance changes could end up causing the application to run more slowly or not at all. A lot of performance improvements end up hurting the user, the data, or the application because the person tuning the application didn’t have proper comments for making the adjustments.


I had previously mentioned the need for good comments. Some developers write comments that are nearly useless. Although it’s hard to encapsulate the substance of a good comment, developers who answer these sorts of questions are well on their way to writing good comments.

 

  • Who is affected by the code?
  • What is the code supposed to do?
  • When is the code supposed to perform this task?
  • Where does the code obtain resources needed to perform the task?
  • Why did the developer use a particular technique to write the code?
  • How does the code accomplish the task without causing problems with other applications or system resources?


There are many other questions you could ask yourself, but these six questions are a good start. You won’t answer every question for every last piece of code in the application because sometimes a question isn’t pertinent. As you work through your code and gain experience, start writing down questions you find yourself asking. Good answers to aggravating questions produce superior comments. Whenever you pull your hair out trying to figure out someone’s code, especially your own, remember that a comment could have saved you time, frustration, and effort. What is your take on comments? Let me know at John@JohnMuellerBooks.com.

 

Inheriting Someone Else’s Code

In my book, “C# Design and Development,” I propose a lot of management techniques that could apply to any language. In fact, I’ve used the techniques in this book successfully for years with Visual Basic, C#, IronPython, C++, and PHP, among many others. The idea behind the concepts in this book is to create code that performs well from the outset and is easy to maintain when changes are required. In today’s environment, you can count on changes at some point. There are many reasons to expect changes:

 

  • The business is bought by someone else and the code must be integrated into a new system.
  • A change in some other component necessitates a change in the application (such as the changes in Vista and Windows 7 security).
  • The business has grown and now needs new features to support its customers.
  • Modifications in the law mean changes to the way the application interacts with data.
  • Technology changes in such a way that the application no longer works properly.

In fact, the reasons for change are endless. I could probably continue writing reasons for change for hours and not cover even a small number of them. The point is that applications will change at some pointit’s simply a matter of time.

If you’ve written code for any time at all, you know that feeling in the pit of your stomach when you discover the perfectly lucid comments you wrote at the time you created the application are no long lucid now. Worse still, the documentation you put together doesn’t tell you what you did and why. Still, after a few hours of looking at your comments and documentation, you can usually begin to fit the pieces together of an application you created because you can recreate the thought patterns you had when you designed and wrote it in the first place.

However, what happens when you’re part of a team or you’re working on an application that someone else designed? Now there isn’t any way to “get back into the groove” of what you did in the past. The thought processes are foreign, so the comments and documentation have to be as comprehensive as possible. Even with great comments and documentation, it’s going to take a while to get up and running with the code.

The longer it takes you to recreate the ideas that went into creating the code, the longer the project update languishes and the more extreme management’s position becomes. The only thing that management knows is that your application (the one you inherited from someone else) is costing the business money. Not only is there a cost associated with the update, but the delay costs the organization money too. Users who have to fight with an outdated application are always unhappy and aren’t productive. So, what techniques can you use to become productive as quickly as possible? That’s what I’d like to know as well. Obviously, reading the documentation and comments are two pieces to the puzzle, but what other techniques do you use?

I’m currently putting an article together that discusses this topic in detail and I’d like to hear about your techniques. If you’ve ever been frustrated by someone else’s code, write me at John@JohnMuellerBooks.com. I’ll let you know when the article is published on Software Quality Connection