Over-indenting is the enemy number one


Link to this posting

Postby Ursego » 21 Feb 2013, 10:42

Indent code fragments with as few tabs as possible.

Avoidance of over-indenting forces us to organize our functions correctly rather than creating one huge unreadable and bugs-prone mess. The key word here is "forces". That will keep our functions simple and easy to work with. Indentation is like salt in a soup: it's a must, but over-use will make the product unfit for consumption. If your code has long "staircases" of closing braces (}), END IFs or other code-branching keywords, then it's a good idea to take your habits critically!

REMARK: Counting tabs, we start from the basic level of left indentation. In languages and IDEs where you open a single function in the editor (like PowerBuilder, Oracle Forms and Transact-SQL), you start writing code with zero tabs (no indentation). But if the editor opens the whole class, then the basic level of left indentation is already 2: one tab to indent the method inside the class, another - to indent the code inside the method - that what we have in Java, .Net and Oracle packages. So, in the last case, consider the basic level of left indentation as zero tabs in the following counts.

From the book "Clean Code":

...the blocks within if statements, else statements, while statements, and so on should be one line long. Probably that line should be a function call. Not only does this keep the enclosing function small, but it also adds documentary value because the function called within the block can have a nicely descriptive name. This also implies that functions should not be large enough to hold nested structures. Therefore, the indent level of a function should not be greater than one or two. This, of course, makes the functions easier to read and understand.


2 tabs are absolutely ok.

3 tabs are ok if the indented fragment it not long. If it's longer than half a screen, then consider extracting the whole fragment into a brand new function. Your 3 tabs will magically become no tabs, so, in the future, you can add a couple of indent levels without causing the wrath of the gods. If the code fragment is executed after a few conditions, checked after each other (so, each condition adds a tab), then use the principle, described in the topic Code after validations.

4 tabs are a "red light" and usually signal about incorrect organization of code structure - in most cases, the code could (and should!) be written in a more elegant way. As an exception, 4 tabs can be used rarely if the indented fragment is just a few lines.

5 tabs: you will burn in hell forever :evil: ! I remember the words of one of my first project managers (a guru of elegant programming):

Do whatever, jump over your head, but avoid indentation of 5 tabs! If I see 5 tabs in your code, you are no more in the project.


Fragments, which logically have the same level of nesting, must be indented with the same amount of tabs.

The single most important formatting convention that you can follow is to indent your programs properly, so indentation conveys the structure of the program to the reader at a glance. Indentation must enlighten, not confuse!

Here is an example of confusing code structure, seen in many-many applications. Logically, the code fragments have the same level of nesting (because, in the end of the day, only one of them will have been executed). But they are indented with different amounts of tabs, so the indentation doesn't help the reader to understand. The example is very simple, but keep in mind, that, in reality, the number of conditions can be much larger, and each code fragment can be long, with its own levels of indentation:

*** BAD code: ***

Code: Select all
if <condition 1> then
   [code fragment 1]
else
   if <condition 2> then
      [code fragment 2]
   else
      if <condition 3> then
         [code fragment 3]
      else
         [code fragment 4]
      end if
   end if
end if

The indentation, though clearly systematic, is not a help. If we eliminate unnecessary grouping, and indent to show that the fragment is basically one if construction, things clarify remarkably. Now, fragments, which logically have the same level of nesting, have the same level of indentation:

*** GOOD code: ***

Code: Select all
if <condition 1> then
   [code fragment 1]
elseif <condition 2> then
   [code fragment 2]
elseif <condition 3> then
   [code fragment 3]
else
   [code fragment 4]
end if

Now we know for certain that one, and only one, case will be executed. Reading from top down until the proper condition is met tells us which one.

In loops, use continue instead of indenting the subsequent code with one more tab.

This method is a heavy weapon in the war against over-indenting:

*** BAD code: ***

Code: Select all
while ([loop condition]) {
   if ([condition 1])  {
      if ([condition 2]) {
         if [condition 3]) {
            [code fragment with its own indenting levels]
         }
      }
   }
}

*** GOOD code: ***

Code: Select all
while ([loop condition]) {
   if (![condition 1]) continue;
   if (![condition 2]) continue;
   if (![condition 3]) continue;
   [code fragment with its own indenting levels]
}
User avatar
Ursego
Site Admin
 
Posts: 130
Joined: 19 Feb 2013, 20:33



IF you want to ((lose weight) OR (have unbelievable (brain function AND mental clarity))) THEN click:




cron
free counters

eXTReMe Tracker