CSC/ECE 517 Summer 2008/wiki2 5 31: Difference between revisions

From Expertiza_Wiki
Jump to navigation Jump to search
Line 38: Line 38:
<b>Another example</b>
<b>Another example</b>


  One of the most common ways to implement the DRY principal is with the use of code generators.  Although it is<br>technically not generating usable code, [http://www.codegeneration.net/tiki-index.php?page=JavaDoc JavaDoc] uses the existing Java code to generate documentation for its code. <br>If the documentation was written independently of the code then changes to the code would very likely require changes <br>in the documentation.  With JavaDoc, since the documentation is generated from the source code, the documentation <br>will still be relevant after maintenance is performed on the code.  Using code generators like JavaDoc helps to <br>allow a single authority on a piece of knowledge within in the code is maintained.  The programmer changes the code <br>and the change is properly documented as a result.
  One of the most common ways to implement the DRY principal is with the use of code generators.  Although it is<br>technically not generating usable code, [http://www.codegeneration.net/tiki-index.php?page=JavaDoc JavaDoc] uses the existing Java code to generate documentation for its code. <br>If the documentation was written independently of the code then changes to the code would very likely require changes <br>in the documentation.  With JavaDoc, since the documentation is generated from the source code, the documentation <br>will still be relevant after maintenance is performed on the code.  Using code generators like JavaDoc helps to <br>allow a single authority on a piece of knowledge within in the code to be maintained.  The programmer changes the code <br>and the change is properly documented as a result.


= Programmer Checklist for the DRY Principle =
= Programmer Checklist for the DRY Principle =

Revision as of 19:28, 25 June 2008

DRY Principle

The Don't Repeat Yourself (DRY) principle is basic to writing maintainable code. The purpose of this Wiki is to find Web sites that explain the importance of the principle by writing prose that summarizes their arguments. Examples will be provided of where the principle should be applied. A checklist will be created for programmers to consider in determining whether their code is in conformance.

What is the DRY Principle?

The DRY philosophy is stated as every piece of knowledge must have a single, unambiguous, authoritative representation within a system. The DRY Principle means you should ensure that every bit of knowledge of your system, be it in the source code, its documentation or any other documentation, should have a single representation.

The Importance of the DRY Principle?

DRY, is also known as Single Point of Truth. This process is aimed at simplifying the maintenance of code. The philosophy emphasizes that information should not be duplicated, because duplication increases the difficulty of change, may decrease clarity, and leads to opportunities for inconsistency. When the DRY principle is applied successfully, a modification of any single element of a system does not change other logically-unrelated elements. Additionally, elements that are logically related all change predictably and uniformly, and are thus kept in sync.

Ultimately, the goal of the DRY principal is to make code maintenance easier. At first glance, some projects may seem like maintenance will not be much of an issue. The project may be very small or the parameters seem defined well enough that, once completed, the project will not need further adjustment. In reality, it is rare that code is ever complete. In fact it has been shown that requirements change at a rate of two percent per month[1]. Even if one were to ignore the possibility of change requirements after code is complete, one must consider the following question: How often is a complete section of code written, never to be altered, on the first try? The truth is that maintenance begins immediately after anyone alters anything in the existing code. In other words, it is virtually impossible not to do maintenance. If data or code is repeated and maintenance needs to be done it will require the programmer to make changes and substitutions everywhere in the code where the repeated data or code exists. Programmers are people and people will make errors. Eventually a replacement will be missed somewhere in the code. Having a single point of truth or authority for a particular piece of data will require the programmer to correctly alter the code in only one location and he or she can be assured the changes will populate correctly throughout the rest of the related code.

Code written following the DRY principle, given its nature, will allow for easier changes and will allow many changes to be made with decreased likelihood of error. Errors introduced late in the development process are typically the most time-consuming and therefore the most expensive to fix. The advantages of having followed the DRY principal increases as the development process progresses. Late in the development process the code will be voluminous (relative to early in development) and more complex. Adherence to the DRY principle will allieviate a significant number of coding errors that would result from the implementation of change to repeated code or data.

Examples of the DRY Principle

Inadvertently, you may introduce duplication into your model without realizing that you are doing so. Suppose you have a class that represents a line as follows:

 class line {
    public:
     Point start;
     Point end;
     double length;
 };

Although this may appear to be a reasonable class for defining a line but we have duplication. If for example we store the start and end points and then the length we will have a problem if one of the points changes. The length will be incorrect. It would be much better to have the length be calculated from the existing start and end points.

 class line {
    public:
     Point start;
     Point end;
     double length() { return start.distanceTo(end); }
 };

Now we are not duplicating any information in our class and are following the principle of Don't Repeat Yourself.


Another example

One of the most common ways to implement the DRY principal is with the use of code generators.  Although it is
technically not generating usable code, JavaDoc uses the existing Java code to generate documentation for its code.
If the documentation was written independently of the code then changes to the code would very likely require changes
in the documentation. With JavaDoc, since the documentation is generated from the source code, the documentation
will still be relevant after maintenance is performed on the code. Using code generators like JavaDoc helps to
allow a single authority on a piece of knowledge within in the code to be maintained. The programmer changes the code
and the change is properly documented as a result.

Programmer Checklist for the DRY Principle

 •If you have duplicated data in your code because it has to have different
representations in different places, can you write a function, tool or code
generator to make one representation from the other, or all from a common source?
•If your documentation duplicates knowledge in your code, can you generate parts of the documentation from parts of the code, or vice-versa, or both from a common higher-level representation?
•If your header files and interface declarations duplicate knowledge in your implementation code, is there a way you can generate the header files and interface declarations from the code?
•If you have metadata, tables, or constants they should be declared once an imported elsewhere.
•If you have reused a section of code, a change will require finding all the sections that involved reuse. Missing some of the changes will often cause very subtle errors.

External Links/References

[1]Hunt, Andy and Thomas, Dave Keep It DRY, SHY, and Tell the Other Guy, IEEE Software, vol. 21, no. 3, pp. 101-103, May/Jun 2004 PMID: 9917440; UI: 99117608.


Back to the assignment page