The reason is simple . . . Software has bugs.

Unfortunately, it is true. Even the good old “Hello World” program can be considered to be buggy.

Developing software means having to deal with defects; old ones, new ones, the ones you created yourself, and those that others have put in the code. Software developers debug programs for a living.

Hence, good debugging skills are a must-have.

We are going to start with generally applicable hints which should not be neglected. We are going to start with the “13 Golden Rules of Debugging“….

1. Understand the Requirements

Make sure you understand the requirements before you begin to debug and fix anything.

2. Make it Fail

You need a test case. Make your program fail. See it with your own eyes

3 .Simplify the Test Case

You do this in order to

• rule out factors that do not play a role,

• reduce the runtime of the test case and, most importantly,

• make the test case easier to debug. Who wants to deal with data containers filled
with hundreds or thousands of items?

4. Read the Right Error Message

Something went wrong and you face a screen full of error messages.

Which ones do you focus on?

It is surprising how many people don’t give the correct answer.

The ones that come out first!

So, first things first – fix the problems in the order of appearance, or have a very good reason for breaking this rule.

5. Check the Plug

Next, check the seemingly obvious. Were all parts of the software up and running when the problem occurred? Permissions OK? Enough disk quota?

Think of ten common mistakes, and ensure nobody made them.

6 .Separate Facts from Interpretation

Don’t jump to conclusions. Maintain a list of things you know for a fact, and why.

Ask yourself: “Can you prove it?” Is the behavior reproducible? Is what you consider a fact really a fact? “It fails when I select a blue item but it always works for red items” a bug report may state. So misbehavior depends on the color? Maybe not. It could be that the user selected the blue item with a mouse click and everything else via the keyboard, by specifying its name.

7 .Divide and Conquer

The National Institute of Standards and Technology defines divide and conquer as an algorithmic technique to “solve a problem, either directly because solving that instance is easy [. . . ] or by dividing it into two or more smaller instances.” And further “the solutions are combined to produce a solution for the original instance.”

This strategy can be successfully applied to debugging in order to deal with complex situations when multiple factors can play a role.

Hint: In the next post we will describe one possible divide-and-conquer approach.

8. Match the Tool to the Bug

Some debugging tools (like GNU) are easier to use than others in a given situation. But not all are equally helpful. It is natural to focus on the tools and processes you feel most comfortable with.

9. One Change at a Time

Do not change more than one thing at a time if possible. Then check if it makes sense and, if not, revert back before trying out the next idea.

10. Keep an Audit Trail

Often you will have to deal with a problem involving multiple parameters. You need to try out a number of combinations. It is all too easy to lose track of your changes.

Keep an audit trail!

This is especially important in the case of spurious failures.

11. Get a Fresh View

When you are stuck, go and find somebody to talk to. Make sure to draw a clear line between the facts – and why they are facts – and your theories. The process of explaining the situation to somebody else may help you to separate truth from myths.

12 .If You Didn’t Fix it, it isn’t Fixed

Occasionally, a bug will just disappear after you modified some statements. Unless you have a good explanation why your fix is effective, you are better off to assume that the bug still exists and will hit again in the future.

13. Cover your Bugfix with a Regression Test

So the problem is fixed . . . today. What about tomorrow? To make the bug fix last, you should turn your simplified test case (rule number3) into a regression test. Think of it as a safety bolt. It prevents others with access to the source code base from accidentally breaking a feature you have put quite some work into.

The term regression test means something along the lines of “check whether yesterday’s functionality is still working well today.” These tests should be automated in order to allow for frequent and efficient execution. And the tests should be self-checking.

Those were our tips for this week. Wait for tips about “Unit Tests and System Test” in the next week

According to Kent, a design is “simple” if it follows these rules:

• Runs all the tests

• Contains no duplication

• Expresses the intent of the programmer

• Minimizes the number of classes and methods

(The rules are given in order of importance.)

Simple Design Rule 1: Runs All the Tests

First and foremost, a design must produce a system that acts as intended.

A system that is comprehensively tested and passes all of its tests all of the time is a testable system.

Systems that aren’t testable aren’t verifiable. Arguably, a system that cannot be verified should never be deployed.

Fortunately, making our systems testable pushes us toward a design where our classes are small and single purpose. So making sure our system is fully testable helps us to create better designs.

Simple Design Rules 2: Refactoring

For each few lines of code we add, we pause and reflect on the new design. So, we clean it up and run our tests to demonstrate that we haven’t broken anything.

The fact that we have these tests eliminates the fear
that cleaning up the code will break it!

No Duplication

Duplication is the primary enemy of a well-designed system. It represents additional work, additional risk, and additional unnecessary complexity.

Duplication forms:

Lines of code that looks exactly alike

Duplication of implementation

The TEMPLATE METHOD pattern is a common technique for removing higher-level duplication.

Expressive

The clearer the author can make the code, the less time others will have to spend understanding it. This will reduce defects and shrink the cost of maintenance.

Design patterns, for example, are largely about communication and expressiveness. By using the standard pattern names, such as COMMAND or VISITOR, in the names of the classes that implement those patterns, you can succinctly describe your design to other developers.

Well-written unit tests are also expressive. A primary goal of tests is to act as documentation by example.

Minimal Classes and Methods

In an effort to make our classes and methods small, we might create too many tiny classes and methods. So this rule suggests that we also keep our function and class counts low. This rule is the lowest priority of the four rules of Simple Design. So, although it’s important to keep class and function count low, it’s more important to have tests, eliminate duplication, and express yourself.

Following the practice of simple design can and does encourage and enable developers to adhere to good principles and patterns that otherwise take years to learn.

• You should take care that your code is nicely formatted. You should choose a set of simple rules that govern the format of your code, and then you should consistently apply those rules.
  
• If you are working on a team, then the team should agree to a single set of formatting rules and all members should comply.
  

The Purpose of Formatting

• Code formatting is about communication, and communication is the professional developer’s first order of business.
  
• The coding style and readability set precedents that continue to affect maintainability and extensibility long after the original code has been changed beyond recognition.
  

The formatting issues that help us to communicate best

• Vertical Formatting
  
  • Vertical size: It turns out that there is a huge range of sizes and some remarkable differences in style.
    
  • It appears to be possible to build significant systems out of files that are typically 200 lines long, with an upper limit of 500. Although this should not be a hard and fast rule, it should be considered very desirable. Small files are usually easier to understand than large files are.
    
  • The Newspaper Metaphor
    

  Think of a well-written newspaper article. You read it vertically. At the top you expect a headline that will tell you what the story is about, We would like a source file to be like a newspaper article. The name should be simple but explanatory. The name, by itself, should be sufficient to tell us whether we are in the right module or not. The topmost parts of the source file should provide the high-level concepts and algorithms. Detail should increase as we move downward, until at the end we find the lowest level functions and details in the source file.
  

  • Vertical Openness Between Concepts
    

  Each line represents an expression or a clause, and each group of lines represents a complete thought. Those thoughts should be separated from each other with blank lines. This extremely simple rule has a profound effect on the visual layout of the code. Each blank line is a visual cue that identifies a new and separate concept. As you scan down the listing, your eye is drawn to the first line that follows a blank line.
  

  • Vertical Density
    

  If openness separates concepts, then vertical density implies close association. So lines of code that are tightly related should appear vertically dense.
  

  • Vertical Distance
    

  Concepts that are closely related should be kept vertically close to each other .Clearly this rule doesn’t work for concepts that belong in separate files. But then closely related concepts should not be separated into different files unless you have a very good reason.
  

  For those concepts that are so closely related that they belong in the same source file, their vertical separation should be a measure of how important each is to the understandability of the other.
  

  Variable Declarations, Variables should be declared as close to their usage as possible. Local variables should appear at the top of each function, control variables for loops should usually be declared within the loop statement (In rare cases a variable might be declared at the top of a block or just before a loop in a long-ish function.)
  

  Instance variables, In C++ we commonly practiced the so-called scissors rule, which put all the instance variables at the bottom, the common convention in Java, however, is to put them all at the top of the class. The important thing is for the instance variables to be declared in one well-known place. Everybody should know where to go to see the declarations.
  

  Dependent Functions, If one function calls another, they should be vertically close, and the caller should be above the callee, if at all possible.
  

  Conceptual Affinity, Certain bits of code want to be near other bits. They have a certain
  conceptual affinity. The stronger that affinity, the
  less vertical distance there should be between
  them. The affinity might be based on a direct dependence (one function calling another, function using variable) OR other possible causes of affinity, it might be caused because a group of functions perform a similar operation.
  

  • Vertical Ordering
    

  In general we want function call dependencies to point in the downward direction. That is, a function that is called should be below a function that does the calling. This creates a nice flow down the source code module from high level to low level. As in newspaper articles, we expect the most important concepts to come first, and we expect them to be expressed with the least amount of polluting detail.
  

• Horizontal Formatting
  

• Programmers clearly prefer short lines. This suggests that we should strive to keep our lines short. The old Hollerith limit of 80 is a bit arbitrary, now it’s not opposed to lines edging out to 100 or even 120. But beyond that is probably just careless.
  
• Horizontal Openness and Density
  

We use horizontal white space to associate things that are strongly related and disassociate things that are more weakly related.

totalChars += lineSize;

The assignment operators were surrounded with white space to accentuate them. The spaces make that separation obvious.

Another use for white space is to accentuate the precedence of operators.

double determinant = determinant (a, b, c);

return (-b + Math.sqrt(determinant)) / (2*a);

The factors have no white space between them because they are high precedence. The terms are separated by white space because addition and subtraction are lower precedence.

• Indentation
  

A source file is a hierarchy rather like an outline. To make the hierarchy of scopes visible, we indent the lines of source code in proportion to their position in the hierarchy.

• Dummy Scopes
  

Sometimes the body of a while or for statement is a dummy (try to avoid them), when u cannot avoid them make sure that the dummy body is properly indented. Unless you make that semicolon visible by indenting it on

its own line, it’s just too hard to see.

• Team Rules
  
  • A team of developers should agree upon a single formatting style, and then every member of that team should use that style. We don’t want it to appear to have been written by a bunch of disagreeing individuals.
    

Remember, a good software system is composed of a set of documents that read nicely. They need to have a consistent and smooth style. The reader needs to be able to trust that the formatting gestures he or she has seen in one source file will mean the same thing in others. The last thing we want to do is add more complexity to the source code by writing it in a jumble of different individual styles.

Comments

• The proper use of comments is to compensate for our failure to express our self in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.
  
• Code changes and evolves. Chunks of it move from here to there. Those chunks bifurcate and reproduce and come together again to form chimeras. Unfortunately the comments don’t always follow them—can’t
  always follow them. And all too often the comments get separated from the code they describe and become orphaned blurbs of ever decreasing accuracy.
  
• It is possible to make the point that programmers should be disciplined enough to keep the comments in a high state of repair, relevance, and accuracy. It’s Okay, But it is better that energy go toward making the code so clear and expressive that it does not need the comments in the first place.
  
• Truth can only be found in one place: the code. Only the code can truly tell you what it does.
• One of the more common motivations for writing comments is bad code. But Comments Do Not Make Up for Bad Code.
  

Good Comments

Legal Comments

• Copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.
  

  // Copyright (C) 2003, 2004, 2005 by Object Mentor, Inc. All rights reserved.
  

  Informative Comments
  

• It is sometimes useful to provide basic information with a comment. For example, consider this comment that explains the return value of an abstract method:

// format matched kk:mm:ss EEE, MMM dd, yyyy

Pattern timeMatcher = Pattern.compile (“\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*”);

Explanation of Intent

• Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision.
  

  Clarification
  

• In general it is better to find a way to make that argument or return value clear in its own right; but when it’s part of the standard library, or in code that you cannot alter, and then a helpful clarifying comment can be useful.
  

  Warning of Consequences
  

• Sometimes it is useful to warn other programmers about certain consequences. For example, here is a comment that explains why a particular test case is turned off:

// Don’t run unless you have some time to kill.

TODO Comments

• TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment, so it is sometimes reasonable to leave “To do” notes in the form of //TODO comments, But you don’t want your code to be littered with TODOs. So scan through them regularly and eliminate the ones you can.
  

  Amplification
  

• A comment may be used to amplify the importance of something that may otherwise seem inconsequential.
  

String listItemContent = match.group (3).trim ();

// the trim is real important. It removes the starting

// spaces that could cause the item to be recognized

// as another list.

new ListItemWidget (this, listItemContent, this.level + 1);

return buildList (text.substring (match.end ()));

Bad Comments

(Most comments fall into this category.)

Mumbling

• If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write or it will turned into mumbling and it will left an enigma behind it
  

  Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes.
  

  Redundant Comments
  

• If the comment is not more informative than the code, or does not justify the code, or provide intent or rationale then it’s a redundant code.
  

  Misleading Comments
  

• Sometimes, with all the best intentions, a programmer makes a statement in his comments that isn’t precise enough to be accurate. This could cause another programmer to blithely call this function in wrong case. That poor programmer would then find himself in a debugging session trying to figure out where is the problem.
  

  Mandated Comments
  

• It is just not rational to have a rule that says that every function must have a doc., or every variable must have a comment. Comments like this just clutter up the code and lend to general confusion and disorganization.
  

  Journal Comments
  

• Sometimes people add a comment to the start of a module every time they edit it. These comments accumulate as a kind of journal, or log, of every change that has ever been made. For example:
  

/*

Changes (from 11-Oct-2001)

————————–

11-Oct-2001: Re-organised the class and moved it to new package

com.jrefinery.date (DG);

05-Nov-2001: Added a getDescription () method, and eliminated NotableDate

Class (DG);

12-Nov-2001: IBD requires setDescription () method, now that NotableDate

class is gone (DG); Changed getPreviousDayOfWeek (),

getFollowingDayOfWeek () and getNearestDayOfWeek () to correct

bugs (DG);

*/

Noise Comments

• Sometimes you see comments that are nothing but noise. They restate the obvious and provide no new information. For example:
  

  /** The day of the month. */
  

  private int dayOfMonth;
  

  Don’t Use a Comment When You Can Use a Function or a Variable
  

• Consider the following stretch of code:
  

  // does the module from the global list <mod> depend on the
  

  // subsystem we are part of?
  

  if (smodule.getDependSubsystems ().contains(subSysMod.getSubSystem()))
  

  This could be rephrased without the comment as
  

  ArrayList moduleDependees = smodule.getDependSubsystems ();
  

  String ourSubSystem = subSysMod.getSubSystem ();
  

  if (moduleDependees.contains (ourSubSystem))
  

  Position Markers
  

• Sometimes programmers like to mark a particular position in a source file. For example, (was found in real program):
  

// Actions //////////////////////////////////

There are rare times when it makes sense to gather certain functions together beneath a banner like this. But in general they are clutter that should be eliminated—especially the noisy train of slashes at the end.

Closing Brace Comments

• Sometimes programmers will put special comments on closing braces. Although this might make sense for long functions with deeply nested structures, it serves only to clutter the kind of small and encapsulated functions that we prefer. So if you find yourself wanting to mark your closing braces, try to shorten your functions instead.
  

  Attributions and Bylines
  

  /* Added by Rick */
  

• There is no need to pollute the code with little bylines. You might think that such comments would be useful in order to help others know who to talk to about the code. But the reality is that they tend to stay around for years and years, getting less and less accurate and relevant.
  
• The best place for this kind of information is the source code control system.
  

  Nonlocal Information
  

• If you must write a comment, then make sure it describes the code it appears near. Don’t offer system wide information in the context of a local comment.
  

  Inobvious Connection
  

• The connection between a comment and the code it describes should be obvious. If you are going to the trouble to write a comment, then at least you’d like the reader to be able to look at the comment and the code and understand what the comment is talking about. Consider, for example:
  

/*

* start with an array that is big enough to hold all the pixels

* (plus filter bytes), and an extra 200 bytes for header info

*/

this.pngBytes = new byte [((this.width + 1) * this.height * 3) + 200];

• The purpose of a comment is to explain code that does not explain itself. It is a pity when a comment needs its own explanation.
  

  Function Headers
  

• Short functions don’t need much description. A well-chosen name for a small function that does one thing is usually better than a comment header.
  

• Nothing can be quite as helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comment. Nothing can be quite as damaging as an old crufty comment that propagates lies and misinformation.
  

Chapter#3:

Functions

• The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.
  
• How short should a function be?
  
  • Functions should hardly ever be 20 lines long, each should be transparently obvious, each should tell a story, and each should lead you to the next in a compelling order.
    
• Blocks within if
  statements, else
  statements, while
  statements, and so on should be one line long. Probably that line should be a function call.
  
• The indent level of a function should not be greater than one or two.
  
• FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL.THEY SHOULD DO IT ONLY.
  
• The reason we write functions is to decompose a larger concept (in other words, the name of the function) into a set of steps at the next level of abstraction.
  
• Functions that do one thing cannot be reasonably divided into sections.
  
• Another way to know that a function is doing more than “one thing” is if you can extract another function from it with a name that is not merely a restatement of its implementation.
  
• Mixing levels of abstraction within a function is always confusing. Readers may not be able to tell whether a particular expression is an essential concept or a detail. Worse, like broken windows, once details are mixed with essential concepts, more and more details tend to accrete within the function.
  

  The Stepdown Rule (Reading Code from Top to Bottom)
  

• It gives the ability to read the program as though it were a set of TO paragraphs, each of which is describing the current level of abstraction and referencing subsequent TO paragraphs at the next level down.
  

  Switch Statements:
  

• The general rule for switch
  statements is that they can be tolerated if they appear only once, are used to create polymorphic objects, and are hidden behind an inheritance relationship so that the rest of the system can’t see them.
  
• Ward’s principle: “You know you are working on clean code when each routine turns out to be pretty much what you expected.” Half the battle to achieving that principle is choosing good names for small functions that do one thing. The smaller and more focused a function is, the easier it is to choose a descriptive name.
  
• Be consistent in your names. Use the same phrases, nouns, and verbs in the function names you choose for your modules.
  
• The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.
  
• Arguments are even harder from a testing point of view. Imagine the difficulty of writing all the test cases to ensure that all the various combinations of arguments work properly.
  
• There are two very common reasons to pass a single argument (monadic) into a function. You may be asking a question about that argument, or you may be operating on that argument, transforming it into something else and returning it.
  
• A function with two arguments (dyadic) is harder to understand than a monadic function. The first argument glides past the eye, easily depositing its meaning. The second requires a short pause until we learn to ignore the first parameter. And that, of course, eventually results in problems because we should never ignore any part of code. The parts we ignore are where the bugs will hide.
  
• There are times, of course, where two arguments are appropriate. This case is ordered components of a single value!
  
• Functions that take three arguments (triadic) are significantly harder to understand than dyads. The issues of ordering, pausing, and ignoring are more than doubled.
  
• A somewhat less common, but still very useful form for a single argument function is an event. In this form there is an input argument but no output argument. The overall program is meant to interpret the function call as an event and use the argument to alter the state of the system.
  

• Flag arguments are ugly. Passing a Boolean into a function is a truly terrible practice. It immediately complicates the signature of the method, loudly proclaiming that this function does more than one thing. It does one thing if the flag is true and another if the flag is false!
  

• When a function seems to need more than two or three arguments, it is likely that some of those arguments ought to be wrapped into a class of their own. Consider, for example:
  
  • Circle makeCircle(double x, double y, double radius);
    
  • Circle makeCircle(Point center, double radius);
    

  When groups of variables are passed together, they are likely part of a concept that deserves a name of its own.
  

• Anything that forces you to check the function signature is equivalent to a double-take. It’s a cognitive break and should be avoided.
  
• Duplication may be the root of all evil in software. Many principles and practices have been created for the purpose of controlling or eliminating it.
  
• Some programmers follow Edsger Dijkstra‘s rules of structured programming.14 Dijkstra said that every function, and every block within a function, should have one entry and one exit. Following these rules means that there should only be one return statement in a function, no break
  or continue
  statements in a loop, and never, ever, any goto statements.
  
• Every system is built from a domain-specific language designed by the programmers to describe that system. Functions are the verbs of that language, and classes are the nouns.
  

Never forget that your real goal is to tell the story of the system, and that the functions you write need to fit cleanly together into a clear and precise language to help you with that telling.

Chapter#2 “Meaningful Names”

Using intention-revealing names:

• Choosing good names takes time but saves more than it takes.
  
• Take care with your names and change them when you find better ones.
  
• The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.
  

Avoid Disinformation:

• Programmers must avoid leaving false clues that obscure the meaning of code.
  
• We should avoid words whose entrenched meanings vary from our intended meaning. For example,
  hp, aix, and
  sco
  would be poor variable names because they are the names of UNIX platforms or variants.
  
• Do not refer to a grouping of accounts as an accountList
  unless it’s actually a List. The word list means something specific to programmers. If the container holding the accounts is not actually a
  List, it may lead to false conclusions. So
  accountGroup
  or
  bunchOfAccounts
  or just plain
  accounts
  would be better.
  
• Beware of using names which vary in small way. (XYZControllerForEfficientHandlingOfStrings,
  

  XYZControllerForEfficientStorageOfStrings)
  

• Spelling similar concepts similarly is
  information, Using inconsistent spellings is
  disinformation.
  

Make Meaningful Distinctions:

• Programmers create problems for themselves when they write code solely to satisfy a compiler or interpreter.
  
• It is not sufficient to add number series (a1, a2… aN)
  or noise words, even though the compiler is satisfied.
  
• Noise words are another meaningless distinction. Imagine that you have a Product
  class. If you have another called ProductInfo
  or
  ProductData, you have made the names different without making them mean anything different.
  Info
  and
  Data
  are indistinct noise words like
  a, an, and
  the.
  
• The word
  variable
  should never appear in a variable name, the word table
  should never appear in a table name.
  
• The variable
  moneyAmount
  is indistinguishable from
  money, customerInfo
  is indistinguishable from customer, accountData
  is indistinguishable from account, and
  theMessage
  is indistinguishable from
  message. Distinguish names in such a way that the reader knows what the differences offer.
  
• A significant part of our brains is dedicated to the concept of words. And words are, by definition, pronounceable. It would be a shame not to take advantage of that huge portion of our brains that has evolved to deal with spoken language. So make your names pronounceable.
  
• This matters because programming is a social activity.
  
• Use Searchable Names:
  
• Single-letter names and numeric constants have a particular problem in that they are not easy to locate across a body of text.
  
• Single-letter names can ONLY be used as local variables inside short methods.
  
• The length of a name should correspond to the size of its scope.
  
• If a variable or constant might be seen or used in multiple places in a body of code, it is imperative to give it a search-friendly name.
  

Avoid Encoding:

• Encoded names are seldom pronounceable and are easy to mis-type.
  
• Hungarian Notation
  
  • 
    FORTRAN forced encodings by making the first letter a code for the type.
    
  • Early versions of BASIC allowed only a letter plus one digit.
    
  • HN was considered to be pretty important back in the Windows C API, when everything was an integer handle or a long pointer or a void pointer, or one of several implementations.
    
  • In modern languages we have much richer type systems, and the compilers remember and enforce the types. So nowadays HN and other forms of type encoding are simply impediments. They make it harder to change the name or type of a variable, function, or class. They make it harder to read the code. And they create the possibility that the encoding system will mislead the reader.
    
• Member Prefixes
  
  • You don’t need to prefix member variables with
    m_
    anymore because the more we read the code, the less we see the prefixes. Eventually the prefixes become unseen clutter and a marker of older code.
    
• Interfaces and Implementations
  
  • These are sometimes a special case for encodings. if you must encode either the interface or the implementation, I choose the implementation.
    
  • Example: an ABSTRACT FACTORY for the creation of shapes will be an interface and will be implemented by a concrete class, what should be its name “IShapeFactory
    or
    ShapeFactory“?! The preceding
    I, so common in today’s legacy wads, is a distraction at best and too much information at worst, you just want them to know that it’s a ShapeFactory.
    

Avoid Mental Mapping:

• Readers shouldn’t have to mentally translate your names into other names they already know. This problem generally arises from a choice to use neither problem domain terms nor solution domain terms.
  
• A loop counter may be named i
  or
  j
  or
  k
  (though never l!) if its scope is very small and no other names can conflict with it, but generally a single-letter name is a poor choice.
  
• One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king.
  

Class Names:

• Classes and objects should have noun or noun phrase names like
  Customer,
  Account, and
  AddressParser. Avoid words like
  Manager, Processor, Data, or
  Info
  in the name of a class. A class name should not be a verb.
  

Method Names:

• Methods should have verb or verb phrase names like
  postPayment, deletePage, or
  save. Accessors, mutators, and predicates should be named for their value and prefixed with get,
  set, and
  is
  according to the JavaBeans standard. (JavaBeans technology is the component architecture for the Java 2 Platform, Standard Edition (J2SE). Components (JavaBeans) are reusable software programs that you can develop and assemble easily to create sophisticated applications.)
  
• When constructors are overloaded, use static factory methods with names that describe the arguments.
  

Tips:

• If names are too clever, they will be memorable only to people who share the author’s sense of humor, and only as long as these people remember the joke. This often appears in the form of colloquialisms or slang. So “Say what you mean. Mean what you say”.
  
• Pick one word for one abstract concept and stick with it. For instance, it’s confusing to have fetch, retrieve, and
  get
  as equivalent methods of different classes.
  

  (Modern editing environments like Eclipse and IntelliJ-provide context-sensitive clues, such list of methods you can call on a given object).
  

• Avoid using the same word for two purposes.
  
• Using the same term for two different ideas is essentially a pun, so follow “one word per concept” rule.
  
• Remember that the people who read your code will be programmers. So go ahead and use computer science (CS) terms, algorithm names, pattern names, math terms and so forth.
  
• When there is no “programmer-eese” for what you’re doing, use the name from the problem domain.
  
• Separating solution and problem domain concepts is part of the job of a good programmer and designer.
  
• Shorter names are generally better than longer ones, so long as they are clear. Add no more context to a name than is necessary.
  
• Imagine that you have variables named
  firstName, lastName, street, houseNumber, city, state, and
  zipcode. Taken together it’s pretty clear that they form an address.But if u want to use state variable alone in a method you can add context by using prefixes “addrState” ,so readers will understand that these variables are part of a larger structure.
  

  (Of course, a better solution is to create a class named
  Address. Then, even the compiler knows that the variables belong to a bigger concept.)
  

The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. Follow some of these rules and see whether you don’t improve the readability of your code. If you are maintaining someone else’s code, use refactoring tools to help resolve these problems. It will pay off in the short term and continue to pay in the long run.

Clean Code

Chapter 1:

“Clean Code”

• Code represents the details of the requirements.
  
• Programming means specifying requirements in such detail that a machine can execute them.
  
• There is a bad code and clean code dealing with bad code is called “wading through a bad code”.
  
• A bad code can bring a company down …there was a company in the late 80s, wrote a killer app. It was very popular, and lots of professionals bought and used it. But then the release cycles began to stretch. Bugs were not repaired from one release to the next. Load times grew and crashes increased, then the company went out of business.
  

  What exactly happened is that the company had rushed the product to market and had made a huge mess in the code. As they added more and more features, the code got worse and worse until they simply could not manage it any longer. It was the bad code that brought the company down.
  

• Never write a program in harry then revise it later according to
  

  LeBlanc’s Law: Later equals never.
  

• When a company team fails to finish a program because of the messy code, another team is collected called “Tiger team” to start coding from the beginning. Then the competition starts between the 2 teams to finish the program, this takes a lot of time it could reach 10 years!!
  
• The key of writing a clean code is “code-sense”. Not only does it let us see whether code is good or bad, but it also shows us the strategy for applying our discipline to transform bad code into clean code.
  
• There are probably as many definitions as there are programmers for clean code. So next are thoughts of some very well-known and deeply experienced programmers:
  
  • Grady Booch, author of Object Oriented Analysis and Design with Applications…“
    

    Clean code reads like well-written prose”.
    

  • “Big” Dave Thomas, founder of OTI, godfather of the Eclipse strategy…“
    

    Clean code can be read, and enhanced by a developer other than its original author.”
    

  • Michael Feathers, author of Working Effectively with Legacy Code…“
    

    I could list all of the qualities that I notice in clean code, but there is one overarching quality that leads to all of them. Clean code always looks like it was written by someone who cares.”
    

  • Ron Jeffries, author of Extreme Programming Installed and Extreme Programming Adventures in C# …
    

    “In recent years I begin, and nearly end, with Beck’s rules of simple code. In priority order, simple code:
    

    • Runs all the tests;
    

    • Contains no duplication;
    

    • Expresses all the design ideas that are in the system.
    

    • Minimizes the number of entities such as classes, methods, functions, and the like.”
    

  • Ward Cunningham, inventor of Wiki, inventor of Fit, co-inventor of eXtreme Programming. Motive force behind Design Patterns. Smalltalk and OO thought leader. The godfather of all those who care about code…
    

    “You can call it beautiful code when the code also makes it look like the language was made for the problem.”
    

  • Bjarne Stroustrup, inventor of C++ and author of The C++ Programming Language…“
    
    

    I like my code to be elegant and efficient “.
    

• Elegance, Efficiency,
  Simplicity, Clarity, Readability and Caring they all share in creating a clean code.
  
• Pragmatic Dave Thomas and Andy Hunt said this in a different way. They used the metaphor of broken windows” A building with broken windows looks like nobody cares about it “. So the next times you write a line of code remember you are an author writing for readers who will judge your effort.