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.

That will keep your scripts 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!

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 checking some conditions, 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 don't use indentation of 5 tabs! If I see 5 tabs in your code, you are no more in the project!

As you see, 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".

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.


Indentation must enlighten, not confuse

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.

Here is an example of confusing code structure, seen in many-many applications. Fragments, which logically have a same level of nesting, have different levels of indentation. 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 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. Fragments, which logically have a same level of nesting, have a 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: 124
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