Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2007/wiki3 8 ss

2007-11-27T06:28:47Z

Spinnam:

'''Topic'''

O-o design guru Bob Martin has developed a set of design principles that relate to packages (one level above the class-oriented strategies we consider in this course). Report on the

* Reuse/Release Equivalency principle,
* Common Closure principle,
* Common Reuse principle,
* Acyclic Dependencies principle,
* Stable Dependencies principle, and
* Stable Abstraction principle

Find the best descriptions and examples of each that you can find on the Web.

= Design principles related to Packages =

Object Oriented Programming (OOP) is a methodology for modeling and designing software systems which encompasses the basic concepts of encapsulation, abstraction, inheritance and polymorphism. This methodology is guided by a set of principles, called the Design Principles. These principles show the right direction of designing and helps in avoiding costly mistakes at the designing stage. The design principles are not important only from a software design point of view, but also from a business because design principles enable flexible designs, which can evolve with the business requirements with minimum effort, time and cost.

There are Class Design principles and Package Design principles, here we will discuss on the Package Design principles alone.

== Bob Martin ==

[http://www.objectmentor.com/omTeam/martin_r.html Robert C. Martin] has been a software professional since 1970. In the last 35 years, he has worked in various capacities on literally hundreds of software projects. He has authored "landmark" books on Agile Programming, Extreme Programming, UML, Object-Oriented Programming, and C++ Programming. He has published dozens of articles in various trade journals. Today, He is one of the software industry's leading authorities on Agile software development and is a regular speaker at international conferences and trade shows. He is a former editor of the C++ Report.

= Reuse/Release Equivalency Principle (REP)=

The Reuse/Release Equivalency Principle (REP) states that

<code>The granule of reuse is the granule of release. Only components that are released through a tracking system can be effectively reused. This granule is the package.</code>

According to this, package is to be considered as the unit of distribution of software. When one wants to reuse components, package has to be the concrete unit that should be reused. The term package may also be interpreted as library, domain, functionality or a set of classes bound together.

An interesting argument can be that, why not use classes as the unit of distribution? The reason is that quiet often by design, we end up with more than one class that communicates with each other. If individual classes are released, tracking version and compatibility can become very difficult. Hence, packages which are in the level next to classes, are the granular units of release and therefore reused even if classes can be the units of design.

The tracking system is important because the author owns the responsibility of upgrading the package that is being reused. Changes or enhancements in the package can be triggered by many factors, like new standards, new requirements, bugs or sometimes new methodologies and technologies. The author has to track the changes in the package along with maintaining its source code.

== Example ==

Let's say one wants use a file operations library. The library itself is the unit of distribution and usage (referred to as the package), even if we use only one particular class for reading a file. The library developed as a package has many functions and only some of them may be used of each person.

= Common Closure Principle (CCP) =

The Common Closure Principle (CCP) states that

<code>The classes in a package should be closed together against the same kind of changes. A change that affects a package affects all the classes in that package.</code>

This principle focuses at maintainability rather than usability. The principle emphasizes those classes which should be packaged together from a change and distribution point of view. Though most of the class design principles advocate loose coupling between classes, so that they can change without affecting the other, dependencies between classes is inevitable. This principle tries to look at classes that are dependent on each other from a code change perspective. Even though Open-Closed Principle (OCP) re-comments full closure to code change, it is not always possible. However this violation should be a conscious decision and the product should be ready for changes because of it.

To enable easy distribution/update/release and maintainability, it is advisable to localize the changes to a package. Only the modified package can then be released, making the update easier. Even if the changes cannot be restricted to a single package, minimal packages should be required to be changed. To get an idea of the code change dependencies, we can take guidance from Law Of Demeter (LOD) principle, which tries to point out classes which know each other’s structures.

== Example ==

A good example for application of CCP is a package modeled after a relational database. Class designs might need to be consciously violated during de-normalization of the database model for performance improvements. During this time changes to the package affects all classes in that package.

= Common Reuse Principle (CRP) =

The Common Reuse Principle (CRP) states that,

<code>The classes in a package are reused together. If you reuse one of the classes in a package, you reuse them all.</code>

This principle stresses on the importance of a package (a set of cohesive classes) to be used for releasing reusable software, and the importance of releasing software that can be tracked, so that the users get a guarantee of interface and behavior from the author. However, it is very important to decide which classes should be bound together by a package. Improper selection of classes can create unwanted dependencies and complicate usage of that package. Common Reuse Principle (CRP) lays down the foundations to determine which classes should be packaged together.

According to this principle, only cohesive classes should be packaged together. The packaging of classes and the cohesiveness should be defined from the user’s perspective. If a user uses a package, all the classes in that package should be reusable in the same context. A rule that can be a derivative of this is that all the classes related to a particular functionality should be packaged together. For example,

As specified by Reuse/Release Equivalency Principle (REP), even if one or two classes are being used, the granularity to be considered is the entire package. This dependency means that with every revision or release of that package, the software has to be tested and revalidated, irrespective of whether the modified class is being used or not. Hence, only those classes should be packaged together which will be reused together.

== Example ==
For a matrix calculations package, it better have only those classes related to matrices and not trigonometric functions.

= Acyclic Dependencies Principle (ADP) =

The Acyclic Dependency Principle (ADP) states that

<code>The dependency structure between packages must be a Directed Acyclic Graph (DAG).</code>

This principle is important from a deployment perspective. A package apart from being reusable and maintainable, should also be deployable. The package design should have defined dependencies so that it is deployment-friendly.

DAG implies that in the package dependency traversal, there should be no path which includes the same package more than once. DAG leads to a clear dependency structure, which can instantly identify the packages that can get affected if a certain package is modified. Cyclic dependencies usually happen when multiple developers work on the same package, on the same module or on the same class. These cyclic dependencies can be broken. One of the methods is to use Dependency Inversion Principle (DIP).The dependency graphs lead directly to the map for building the packages and the entire application. Considering this at the early stages of package design saves lot of time and effort.

== Example ==

The simplest cyclic dependency means that a package A depends on package B, which again depends on package A. Not only does this lead to wrong class dependencies, but also makes deployment a difficult and un-maintainable.

= Stable Dependencies Principle (SDP) =

The Stable Dependencies Principle (SDP) states that

<code>The dependencies between packages in a design should be in the direction of the stability of the packages. A package should only depend upon packages that are more stable that it is.</code>

According to this principle, a package can be considered stable if it is not changed frequently, or if there is no need to change it frequently. Therefore, packages can reliably depend on this stable package. This principle can go to an atomic level of classes and say that classes should depend on more stable classes only. This is a direct derivation of the Dependency Inversion Principle (DIP). Why do we need to look at stability point of view? We need to do this as we define a dependency chain, which can help in localising the changes and create a system which is still flexible but not prone to erroneous changes.

Quiet often, a single change in a class and hence a package triggers a chain-reaction causing changes to more than expected places. This is a classic case leading to overflow of estimates and sometimes leading to failure. By applying SDP the typical chain reaction can be avoided, as the more stable packages are lower in the chain. It is important to identify stable packages and unstable packages. The packages that are expected to changes should be designed to change and acknowledged accordingly. This information can give a better handle on the changes to be done and the corresponding estimates.

== Example ==

An interface called <code>Logger</code> will be more stable than classes <code>FileLogger</code> or <code>DBLogger</code>

= Stable Abstraction Principle (SAP) =

Stable Abstraction Principle (SAP) states that

<code>Packages that are maximally stable should be maximally abstract. Instable packages should be concrete. The abstraction of a package should be in proportion to its stability.</code>

Stable Abstractions Principle (SAP) can be considered to be a corollary of the Stable Dependencies Principle (SDP), which said that packages should depend only on more stable packages. Applying Dependency Inversion Principle (DIP), flexibility is built into a design by introducing abstract classes. Concrete classes depend on the abstract classes for re-usability and extensibility. An abstract class tends to be more stable, as it does not depend on concrete classes. The concrete classes, which are instable, and are expected to change, depend on the concrete classes. This ultimately means that dependencies in packages are in the direction of abstraction.

== Example ==

Let's try to explain this by discussion. An abstraction is used to contain high-level design, which is used to hold the concept. Objects of concepts don’t exist in nature, and rightly so abstract classes cannot be instantiated. The concrete classes which depend on the abstractions are instantiated and can be modeled after the real world objects. As time goes by, the real world objects change more frequently than the concept itself. This leads us to a corollary that abstraction brings stability.

= References =

=== Books ===

# [http://www.amazon.com/Designing-Object-Oriented-Applications-Method/dp/0132038374 Designing Object-Oriented C++ Applications using the Booch Method]
# [http://www.amazon.com/Software-Development-Principles-Patterns-Practices/dp/0135974445 Agile Software Development: Principles, Patterns and Practices]

=== Links ===

# [http://labs.cs.utt.ro/labs/acs/html/lectures/6/lecture6.pdf Principles of Object-oriented design]
# [http://staff.cs.utu.fi/kurssit/Programming-III/PackageDesing.pdf Presentation on package design principles]
# [http://tdoks.blogspot.com/2007/02/principles-of-software-development.html Principles of Software Development]

=== See Also ===
# [http://www.java-entrepreneur.com/50226711/design_patterns_versus_design_principles.php Design Patterns Vs Design Principles]
# [http://www.artima.com/forums/flat.jsp?forum=276&thread=134747 Discussion on Design Patterns Vs Design Principles]
# [http://www.xp.co.nz/Coding_Standards_for_Java.htm Extreme programming and Design Principles]

CSC/ECE 517 Fall 2007/wiki3 8 ss

2007-11-27T05:43:18Z

Spinnam:

'''Topic'''

O-o design guru Bob Martin has developed a set of design principles that relate to packages (one level above the class-oriented strategies we consider in this course). Report on the

* Reuse/Release Equivalency principle,
* Common Closure principle,
* Common Reuse principle,
* Acyclic Dependencies principle,
* Stable Dependencies principle, and
* Stable Abstraction principle

Find the best descriptions and examples of each that you can find on the Web.

= Design principles related to Packages =

Object Oriented Programming (OOP) is a methodology for modeling and designing software systems which encompasses the basic concepts of encapsulation, abstraction, inheritance and polymorphism. This methodology is guided by a set of principles, called the Design Principles. These principles show the right direction of designing and helps in avoiding costly mistakes at the designing stage. The design principles are not important only from a software design point of view, but also from a business because design principles enable flexible designs, which can evolve with the business requirements with minimum effort, time and cost.

There are Class Design principles and Package Design principles, here we will discuss on the Package Design principles alone.

== Bob Martin ==

[http://www.objectmentor.com/omTeam/martin_r.html Robert C. Martin] has been a software professional since 1970. In the last 35 years, he has worked in various capacities on literally hundreds of software projects. He has authored "landmark" books on Agile Programming, Extreme Programming, UML, Object-Oriented Programming, and C++ Programming. He has published dozens of articles in various trade journals. Today, He is one of the software industry's leading authorities on Agile software development and is a regular speaker at international conferences and trade shows. He is a former editor of the C++ Report.

= Reuse/Release Equivalency Principle (REP)=

The Reuse/Release Equivalency Principle (REP) states that

<code>The granule of reuse is the granule of release. Only components that are released through a tracking system can be effectively reused. This granule is the package.</code>

According to this, package is to be considered as the unit of distribution of software. When one wants to reuse components, package has to be the concrete unit that should be reused. The term package may also be interpreted as library, domain, functionality or a set of classes bound together.

An interesting argument can be that, why not use classes as the unit of distribution? The reason is that quiet often by design, we end up with more than one class that communicates with each other. If individual classes are released, tracking version and compatibility can become very difficult. Hence, packages which are in the level next to classes, are the granular units of release and therefore reused even if classes can be the units of design.

The tracking system is important because the author owns the responsibility of upgrading the package that is being reused. Changes or enhancements in the package can be triggered by many factors, like new standards, new requirements, bugs or sometimes new methodologies and technologies. The author has to track the changes in the package along with maintaining its source code.

== Example ==

Let's say one wants use a file operations library. The library itself is the unit of distribution and usage (referred to as the package), even if we use only one particular class for reading a file.

= Common Closure Principle (CCP) =

The Common Closure Principle (CCP) states that

<code>The classes in a package should be closed together against the same kind of changes. A change that affects a package affects all the classes in that package.</code>

This principle focuses at maintainability rather than usability. The principle emphasizes those classes which should be packaged together from a change and distribution point of view. Though most of the class design principles advocate loose coupling between classes, so that they can change without affecting the other, dependencies between classes is inevitable. This principle tries to look at classes that are dependent on each other from a code change perspective. Even though Open-Closed Principle (OCP) re-comments full closure to code change, it is not always possible. However this violation should be a conscious decision and the product should be ready for changes because of it.

To enable easy distribution/update/release and maintainability, it is advisable to localize the changes to a package. Only the modified package can then be released, making the update easier. Even if the changes cannot be restricted to a single package, minimal packages should be required to be changed. To get an idea of the code change dependencies, we can take guidance from Law Of Demeter (LOD) principle, which tries to point out classes which know each other’s structures.

== Example ==

A good example for application of CCP is a package modeled after a relational database. Class designs might need to be consciously violated during de-normalization of the database model for performance improvements. During this time changes to the package affects all classes in that package.

= Common Reuse Principle (CRP) =

The Common Reuse Principle (CRP) states that,

<code>The classes in a package are reused together. If you reuse one of the classes in a package, you reuse them all.</code>

This principle stresses on the importance of a package (a set of cohesive classes) to be used for releasing reusable software, and the importance of releasing software that can be tracked, so that the users get a guarantee of interface and behavior from the author. However, it is very important to decide which classes should be bound together by a package. Improper selection of classes can create unwanted dependencies and complicate usage of that package. Common Reuse Principle (CRP) lays down the foundations to determine which classes should be packaged together.

According to this principle, only cohesive classes should be packaged together. The packaging of classes and the cohesiveness should be defined from the user’s perspective. If a user uses a package, all the classes in that package should be reusable in the same context. A rule that can be a derivative of this is that all the classes related to a particular functionality should be packaged together. For example,

As specified by Reuse/Release Equivalency Principle (REP), even if one or two classes are being used, the granularity to be considered is the entire package. This dependency means that with every revision or release of that package, the software has to be tested and revalidated, irrespective of whether the modified class is being used or not. Hence, only those classes should be packaged together which will be reused together.

== Example ==
For a matrix calculations package, it better have only those classes related to matrices and not trigonometric functions.

= Acyclic Dependencies Principle (ADP) =

The Acyclic Dependency Principle (ADP) states that

<code>The dependency structure between packages must be a Directed Acyclic Graph (DAG).</code>

This principle is important from a deployment perspective. A package apart from being reusable and maintainable, should also be deployable. The package design should have defined dependencies so that it is deployment-friendly.

DAG implies that in the package dependency traversal, there should be no path which includes the same package more than once. DAG leads to a clear dependency structure, which can instantly identify the packages that can get affected if a certain package is modified. Cyclic dependencies usually happen when multiple developers work on the same package, on the same module or on the same class. These cyclic dependencies can be broken. One of the methods is to use Dependency Inversion Principle (DIP).The dependency graphs lead directly to the map for building the packages and the entire application. Considering this at the early stages of package design saves lot of time and effort.

== Example ==

The simplest cyclic dependency means that a package A depends on package B, which again depends on package A. Not only does this lead to wrong class dependencies, but also makes deployment a difficult and un-maintainable.

= Stable Dependencies Principle (SDP) =

The Stable Dependencies Principle (SDP) states that

<code>The dependencies between packages in a design should be in the direction of the stability of the packages. A package should only depend upon packages that are more stable that it is.</code>

According to this principle, a package can be considered stable if it is not changed frequently, or if there is no need to change it frequently. Therefore, packages can reliably depend on this stable package. This principle can go to an atomic level of classes and say that classes should depend on more stable classes only. This is a direct derivation of the Dependency Inversion Principle (DIP). Why do we need to look at stability point of view? We need to do this as we define a dependency chain, which can help in localising the changes and create a system which is still flexible but not prone to erroneous changes.

Quiet often, a single change in a class and hence a package triggers a chain-reaction causing changes to more than expected places. This is a classic case leading to overflow of estimates and sometimes leading to failure. By applying SDP the typical chain reaction can be avoided, as the more stable packages are lower in the chain. It is important to identify stable packages and unstable packages. The packages that are expected to changes should be designed to change and acknowledged accordingly. This information can give a better handle on the changes to be done and the corresponding estimates.

== Example ==

An interface called <code>Logger</code> will be more stable than classes <code>FileLogger</code> or <code>DBLogger</code>

= Stable Abstraction Principle (SAP) =

Stable Abstraction Principle (SAP) states that

<code>Packages that are maximally stable should be maximally abstract. Instable packages should be concrete. The abstraction of a package should be in proportion to its stability.</code>

Stable Abstractions Principle (SAP) can be considered to be a corollary of the Stable Dependencies Principle (SDP), which said that packages should depend only on more stable packages. Applying Dependency Inversion Principle (DIP), flexibility is built into a design by introducing abstract classes. Concrete classes depend on the abstract classes for re-usability and extensibility. An abstract class tends to be more stable, as it does not depend on concrete classes. The concrete classes, which are instable, and are expected to change, depend on the concrete classes. This ultimately means that dependencies in packages are in the direction of abstraction.

== Example ==

Let's try to explain this by discussion. An abstraction is used to contain high-level design, which is used to hold the concept. Objects of concepts don’t exist in nature, and rightly so abstract classes cannot be instantiated. The concrete classes which depend on the abstractions are instantiated and can be modeled after the real world objects. As time goes by, the real world objects change more frequently than the concept itself. This leads us to a corollary that abstraction brings stability.

= References =

=== Books ===

# [http://www.amazon.com/Designing-Object-Oriented-Applications-Method/dp/0132038374 Designing Object-Oriented C++ Applications using the Booch Method]
# [http://www.amazon.com/Software-Development-Principles-Patterns-Practices/dp/0135974445 Agile Software Development: Principles, Patterns and Practices]

=== Links ===

# [http://labs.cs.utt.ro/labs/acs/html/lectures/6/lecture6.pdf Principles of Object-oriented design]
# [http://staff.cs.utu.fi/kurssit/Programming-III/PackageDesing.pdf Presentation on package design principles]
# [http://tdoks.blogspot.com/2007/02/principles-of-software-development.html Principles of Software Development]

=== See Also ===
# [http://www.java-entrepreneur.com/50226711/design_patterns_versus_design_principles.php Design Patterns Vs Design Principles]
# [http://www.artima.com/forums/flat.jsp?forum=276&thread=134747 Discussion on Design Patterns Vs Design Principles]
# [http://www.xp.co.nz/Coding_Standards_for_Java.htm Extreme programming and Design Principles]

CSC/ECE 517 Fall 2007/wiki2 9 A3

2007-10-24T00:51:58Z

Spinnam: /* What is 'Principle of Least Astonishment'? */

==What is 'Principle of Least Astonishment'?==
The Principle of Least Astonishment states that the result of performing some operation should be obvious, consistent, and predictable, based upon the name of the operation and other clues. This axiom states that you should do your utmost to write stuff that is not going to astonish, dismay, or confuse the next person who has to look at it later. When two elements of an interface conflict or are ambiguous, the behaviour should be that which will least surprise the human user or programmer at the time the conflict arises, because the least surprising behavior will usually be the correct one.

# Consistency ("Principle of least astonishment")

* certain aspects of an interface should behave in consistent ways at all times for all screens
* terminology should be consistent between screens
* icons should be consistent between screens
* colors should be consistent between screens of similar function

===Example===
The name of a function should reflect what it does. Otherwise, a user of the function will be unpleasantly surprised: [2]

====Bad design:====
int calculate_salary(int days, int perday)
{
printf("The customer has worked for %d days and his salary per day is %d dollars", a, b);
}

====Better design:====
int calculte_salary(int days, int perday)
{
return days * perday;
}

As can be seen in the example above, in the first example the name of the method and its functionality does not match. Whereas a better way of coding is the second one in which the functionality and the method name are related.

Good examples can be found at the following websites:
* [http://en.wikipedia.org/wiki/Principle_of_least_astonishment User interface]
* [http://benpryor.com/blog/index.php?/archives/19-API-Design-The-Principle-of-Least-Surprise.html API-Design]
* [http://www.agileprogrammer.com/oneagilecoder/archive/2005/06/11/3689.aspx Whidbey System.Configuration]
* [http://daniel.gredler.net/2007/05/ HtmlUnit]
* [http://www.gigascale.org/pubs/949.html Verification Through the Principle of Least Astonishment]
* [http://www.cincomsmalltalk.com/blog/blogView?showComments=true&entry=3258158706 How to design Good APIs]
* [http://jooto.com/blog/index.php/2006/06/06/principle-of-least-astonishment/ Yield]
* [http://www.ibm.com/developerworks/web/library/us-cranky10.html Button on Visual browsers]
* [http://www.ibm.com/developerworks/web/library/us-cranky10.html Application development]

<br>In addition to function naming, the principle applies to user interface design. Menu items and other controls should have an effect that is obvious based upon their text labels and placement relative to other controls.

== Principle of Least Astonishment in fields other than programming ==
Principle of Least Astonishment is a very common principle that is used in every day life.

===Riding in Traffic===
The principle of least astonishment can be translated as "ride predictably" i.e. riding in such a way that minimizes surprise. A complete article on it can be found at [http://www.mile43.com/peterson/Safety%20First.html Riding in Traffic]

===Moon Walker===
A very good article can be found at [http://www.newyorker.com/archive/2005/10/03/051003crbo_books?currentPage=1 How Neil Armstrong brought the space program down to earth]. On page 3, Armstrong mentions about principle of least astonishment.

===Steens Mountain===
A decade ago, Prévot and Coe (and colleagues) reported in three papers the evidence they had found of extremely rapid changes of the Earth’s magnetic field recorded in lava flows at Steens Mountain in southern Oregon (USA). The complete article can be found at [http://www.answersingenesis.org/tj/v9/i2/astonishment.asp Steens Mountain] which describes how geomagnetists applied principle of least astonishment.

===Guide to writing better articles ===
The [http://en.wikipedia.org/wiki/Wikipedia:Guide_to_writing_better_articles#Principle_of_least_astonishment Guide to writing better articles] webpage gives advice on how to write an effective article. It includes material from a number of currently or formerly separate pages into an easy to consult overview. It states that when the principle of least astonishment is successfully employed, the information is apprehended by the reader without struggle. The average reader should not be shocked, surprised, or overwhelmingly confused by the article written. For complete article refer to the link provided.

===Astrophysics===
The [http://www.owlnet.rice.edu/~jeffreyh/LRP/intro.html Astrophysics] webpage talks about works that involved Principle of Least Astonishment in Astrophysics.

== See Also ==
http://doodleplex.com/glassmaze/2004/10/

== References ==
[1] http://www.faqs.org/docs/artu/ch11s01.html <br>
[2] http://c2.com/cgi/wiki?PrincipleOfLeastAstonishment<br>
[3] http://www.cs.arizona.edu/projects/sumatra/hallofshame <br>
[4] http://www.ibm.com/developerworks/library/us-cranky10.html?dwzone=usability<br>
[5] http://ergo.human.cornell.edu/ahtutorials/interface.html

CSC/ECE 517 Fall 2007/wiki2 9 A3

2007-10-24T00:51:08Z

Spinnam: /* References */

==What is 'Principle of Least Astonishment'?==
The Principle of Least Astonishment states that the result of performing some operation should be obvious, consistent, and predictable, based upon the name of the operation and other clues. This axiom states that you should do your utmost to write stuff that is not going to astonish, dismay, or confuse the next person who has to look at it later. When two elements of an interface conflict or are ambiguous, the behaviour should be that which will least surprise the human user or programmer at the time the conflict arises, because the least surprising behavior will usually be the correct one.

===Example===
The name of a function should reflect what it does. Otherwise, a user of the function will be unpleasantly surprised: [2]

====Bad design:====
int calculate_salary(int days, int perday)
{
printf("The customer has worked for %d days and his salary per day is %d dollars", a, b);
}

====Better design:====
int calculte_salary(int days, int perday)
{
return days * perday;
}

As can be seen in the example above, in the first example the name of the method and its functionality does not match. Whereas a better way of coding is the second one in which the functionality and the method name are related.

Good examples can be found at the following websites:
* [http://en.wikipedia.org/wiki/Principle_of_least_astonishment User interface]
* [http://benpryor.com/blog/index.php?/archives/19-API-Design-The-Principle-of-Least-Surprise.html API-Design]
* [http://www.agileprogrammer.com/oneagilecoder/archive/2005/06/11/3689.aspx Whidbey System.Configuration]
* [http://daniel.gredler.net/2007/05/ HtmlUnit]
* [http://www.gigascale.org/pubs/949.html Verification Through the Principle of Least Astonishment]
* [http://www.cincomsmalltalk.com/blog/blogView?showComments=true&entry=3258158706 How to design Good APIs]
* [http://jooto.com/blog/index.php/2006/06/06/principle-of-least-astonishment/ Yield]
* [http://www.ibm.com/developerworks/web/library/us-cranky10.html Button on Visual browsers]
* [http://www.ibm.com/developerworks/web/library/us-cranky10.html Application development]

<br>In addition to function naming, the principle applies to user interface design. Menu items and other controls should have an effect that is obvious based upon their text labels and placement relative to other controls.

== Principle of Least Astonishment in fields other than programming ==
Principle of Least Astonishment is a very common principle that is used in every day life.

===Riding in Traffic===
The principle of least astonishment can be translated as "ride predictably" i.e. riding in such a way that minimizes surprise. A complete article on it can be found at [http://www.mile43.com/peterson/Safety%20First.html Riding in Traffic]

===Moon Walker===
A very good article can be found at [http://www.newyorker.com/archive/2005/10/03/051003crbo_books?currentPage=1 How Neil Armstrong brought the space program down to earth]. On page 3, Armstrong mentions about principle of least astonishment.

===Steens Mountain===
A decade ago, Prévot and Coe (and colleagues) reported in three papers the evidence they had found of extremely rapid changes of the Earth’s magnetic field recorded in lava flows at Steens Mountain in southern Oregon (USA). The complete article can be found at [http://www.answersingenesis.org/tj/v9/i2/astonishment.asp Steens Mountain] which describes how geomagnetists applied principle of least astonishment.

===Guide to writing better articles ===
The [http://en.wikipedia.org/wiki/Wikipedia:Guide_to_writing_better_articles#Principle_of_least_astonishment Guide to writing better articles] webpage gives advice on how to write an effective article. It includes material from a number of currently or formerly separate pages into an easy to consult overview. It states that when the principle of least astonishment is successfully employed, the information is apprehended by the reader without struggle. The average reader should not be shocked, surprised, or overwhelmingly confused by the article written. For complete article refer to the link provided.

===Astrophysics===
The [http://www.owlnet.rice.edu/~jeffreyh/LRP/intro.html Astrophysics] webpage talks about works that involved Principle of Least Astonishment in Astrophysics.

== See Also ==
http://doodleplex.com/glassmaze/2004/10/

== References ==
[1] http://www.faqs.org/docs/artu/ch11s01.html <br>
[2] http://c2.com/cgi/wiki?PrincipleOfLeastAstonishment<br>
[3] http://www.cs.arizona.edu/projects/sumatra/hallofshame <br>
[4] http://www.ibm.com/developerworks/library/us-cranky10.html?dwzone=usability<br>
[5] http://ergo.human.cornell.edu/ahtutorials/interface.html

CSC/ECE 517 Fall 2007/wiki2 9 A3

2007-10-24T00:50:50Z

Spinnam: /* References */

==What is 'Principle of Least Astonishment'?==
The Principle of Least Astonishment states that the result of performing some operation should be obvious, consistent, and predictable, based upon the name of the operation and other clues. This axiom states that you should do your utmost to write stuff that is not going to astonish, dismay, or confuse the next person who has to look at it later. When two elements of an interface conflict or are ambiguous, the behaviour should be that which will least surprise the human user or programmer at the time the conflict arises, because the least surprising behavior will usually be the correct one.

===Example===
The name of a function should reflect what it does. Otherwise, a user of the function will be unpleasantly surprised: [2]

====Bad design:====
int calculate_salary(int days, int perday)
{
printf("The customer has worked for %d days and his salary per day is %d dollars", a, b);
}

====Better design:====
int calculte_salary(int days, int perday)
{
return days * perday;
}

As can be seen in the example above, in the first example the name of the method and its functionality does not match. Whereas a better way of coding is the second one in which the functionality and the method name are related.

Good examples can be found at the following websites:
* [http://en.wikipedia.org/wiki/Principle_of_least_astonishment User interface]
* [http://benpryor.com/blog/index.php?/archives/19-API-Design-The-Principle-of-Least-Surprise.html API-Design]
* [http://www.agileprogrammer.com/oneagilecoder/archive/2005/06/11/3689.aspx Whidbey System.Configuration]
* [http://daniel.gredler.net/2007/05/ HtmlUnit]
* [http://www.gigascale.org/pubs/949.html Verification Through the Principle of Least Astonishment]
* [http://www.cincomsmalltalk.com/blog/blogView?showComments=true&entry=3258158706 How to design Good APIs]
* [http://jooto.com/blog/index.php/2006/06/06/principle-of-least-astonishment/ Yield]
* [http://www.ibm.com/developerworks/web/library/us-cranky10.html Button on Visual browsers]
* [http://www.ibm.com/developerworks/web/library/us-cranky10.html Application development]

<br>In addition to function naming, the principle applies to user interface design. Menu items and other controls should have an effect that is obvious based upon their text labels and placement relative to other controls.

== Principle of Least Astonishment in fields other than programming ==
Principle of Least Astonishment is a very common principle that is used in every day life.

===Riding in Traffic===
The principle of least astonishment can be translated as "ride predictably" i.e. riding in such a way that minimizes surprise. A complete article on it can be found at [http://www.mile43.com/peterson/Safety%20First.html Riding in Traffic]

===Moon Walker===
A very good article can be found at [http://www.newyorker.com/archive/2005/10/03/051003crbo_books?currentPage=1 How Neil Armstrong brought the space program down to earth]. On page 3, Armstrong mentions about principle of least astonishment.

===Steens Mountain===
A decade ago, Prévot and Coe (and colleagues) reported in three papers the evidence they had found of extremely rapid changes of the Earth’s magnetic field recorded in lava flows at Steens Mountain in southern Oregon (USA). The complete article can be found at [http://www.answersingenesis.org/tj/v9/i2/astonishment.asp Steens Mountain] which describes how geomagnetists applied principle of least astonishment.

===Guide to writing better articles ===
The [http://en.wikipedia.org/wiki/Wikipedia:Guide_to_writing_better_articles#Principle_of_least_astonishment Guide to writing better articles] webpage gives advice on how to write an effective article. It includes material from a number of currently or formerly separate pages into an easy to consult overview. It states that when the principle of least astonishment is successfully employed, the information is apprehended by the reader without struggle. The average reader should not be shocked, surprised, or overwhelmingly confused by the article written. For complete article refer to the link provided.

===Astrophysics===
The [http://www.owlnet.rice.edu/~jeffreyh/LRP/intro.html Astrophysics] webpage talks about works that involved Principle of Least Astonishment in Astrophysics.

== See Also ==
http://doodleplex.com/glassmaze/2004/10/

== References ==
[1] http://www.faqs.org/docs/artu/ch11s01.html <br>
[2] http://c2.com/cgi/wiki?PrincipleOfLeastAstonishment<br>
[3] http://www.cs.arizona.edu/projects/sumatra/hallofshame <br>
[4] http://www.ibm.com/developerworks/library/us-cranky10.html?dwzone=usability
[5] http://ergo.human.cornell.edu/ahtutorials/interface.html

CSC/ECE 517 Fall 2007/wiki2 9 A3

2007-10-24T00:02:41Z

Spinnam:

CSC/ECE 517 Fall 2007/wiki1 6 c9

2007-09-20T01:44:02Z

Spinnam:

<b><center>Topic 6: Mixins</center></b>

Compare the use of Ruby mixins with how one would solve the same problem in Java or C++. In Java, you might use interfaces or the
decorator pattern (p. 91 of Head-First Design Patterns). In C++, you would probably use multiple inheritance. Give code in all
three languages and compare the solutions on the basis of verbosity and elegance.

<h2>Inheritance and Mixins</h2>

Some object-oriented languages (notably C++) support multiple inheritance, where a class can have more than one immediate parent, inheriting functionality from each. Although powerful, this technique can be dangerous, as the inheritance hierarchy can become ambiguous.
Ruby offers an interesting and powerful compromise, giving you the simplicity of single inheritance and the power of multiple inheritance. A Ruby class can have only one direct parent (i.e no class can inherit from more than one class) and so Ruby is a single-inheritance language. In cases where you want numerous extra behaviors for a class’s instances, Ruby classes provide the multiple inheritance functionality by using mixins. You can use include any number of mixins (a mixin is like a partial class definition). This provides a controlled multiple-inheritance-like capability with none of the drawbacks.

<h3> Modules and Mixins </h3>

A module looks very similar to class. Modules can have methods, constants and classes. Modules provide a means for grouping related methods, constants and classes. They provide a means for implementing multiple inheritance in Ruby. There are two major features that classes possess but that modules do not: instances and inheritance. Classes can have instances (objects), superclasses (parents) and subclasses (children); modules can have none of these.

The process of including a module in a class is also called ‘mixing in’ the module – which explains why included modules are often called ‘mixins’.
An object can access the instance methods of a module just by including that module using the include method.

<h2>Sample</h2>
<pre>
module SampleMixin
def do_something
puts “doing something”
end
end

class SampleClass
include SampleMixin
end

s=SampleClass.new
s.do_something
</pre>

<h2>Include </h2>

A couple of points about the ''include'' statement. It has nothing to do with files. C programmers use a preprocessor directive called #include to insert the contents of one file into another during compilation. The Ruby ''include'' statement simply makes a reference to a named module. If that module is in a separate file, you must use require to drag that file in before using ''include''. Second, a Ruby include does not simply copy the module's instance methods into the class. Instead, it makes a reference from the class to the included module. If multiple classes include that module, they'll all point to the same thing. If you change the definition of a method within a module, even while your program is running, all classes that include that module will exhibit the new behavior.

<h2>Including Modules From Files</h2>

Often it is more useful to define modules in separate files and include them as needed. The first thing you have to do in order to use code from another file is to load that file using the require method, like this:
require( "testmod.rb" )

The required file must be in the current directory, on the search path or in a folder listed in the predefined array variable $:. You can add a directory to this array variable using the usual array-append method, << in this way:
$: << "C:/mydir"
The require method returns a true value if the specified file is successfully loaded; otherwise it returns false. If in doubt, you can simply display the result:
puts(require( "testmod.rb" ))

Pre-Defined Modules

The following modules are built in to the Ruby interpreter:
Comparable, Enumerable, FileTest, GC, Kernel, Math, ObjectSpace, Precision, Process, Signal

<center><h2>EXAMPLE</h2></center>

Consider a scenario of an employee. An employee has the features of a person ( having name,age and other attributes) and also that of an employee( having salary, hours of work and other attributes). In our example, we explain multiple inheritance by showing how modules "Emplike" and "Personlike" are inherited by "Employee" class. Thus we illustrate mixins in ruby.

'''Implementation in Ruby '''
<pre>
module Personlike
attr_accessor :name
attr_accessor :age
def getname
return "#{name}"
end
def getage
return "#{age}"
end
end

module Emplike
attr_accessor :salary
def getsalary
return "#{salary}"
end
end

class Employee
include Personlike
include Emplike
end

s=Employee.new
s.name="Federer"
s.age=26
s.salary=100000
puts (s.getname)
puts(s.getage)
puts(s.getsalary)

Output:
Federer
26
100000
</pre>

The class Employee includes modules Personlike and Emplike. So we can access the methods getname(), getage() and getsalary() as if they are methods in Employee class itself. This provides the functionality of multiple inheritance using mixins.

<h3>Disadvantages of Mixins in Ruby</h3>

A mixin will not warn if the mixin and the user define the same method.(i.e if there are methods with same name in mixin and also in the class, the method in the class is executed without warning the user).

Consider the above example: Incase we include a getsalary method in both the module and also in the class, the method in the class is executed without warning.

<pre>
module Emplike
attr_accessor :salary
def getsalary
return "#{salary}"
end
end

class Employee
include Personlike
include Emplike
def getsalary
return" This is the salary of user defined getsalary"
end
end

s=Employee.new
s.salary=100000
puts(s.getsalary)

Output:
This is the salary of user defined getsalary

</pre>

<h2>Implementation in Java</h2>

The class "emp" implements "emplike" and "personlike" packages in this example.

<pre>
package assignment;

public interface personlike {
String getname();
int getage();
}

package assignment;

public interface emplike {
float getsalary();
}

package assignment;

public class emp implements assignment.emplike,assignment.personlike
{
String name1;
int age1;
float salary1;
emp(String name,int age,float salary)
{
name1=name;age1=age;salary1=salary;
}
public String getname()
{
return name1;
}
public int getage()
{
return age1;
}
public float getsalary()
{
return salary1;
}
}

package assignment;

public class emptest {

public static void main(String args[])
{
emp ob=new emp("Federer",26,100000);
String name=ob.getname();
int age=ob.getage();
float sal=ob.getsalary();
System.out.println("name is "+name+"age is "+age+"salary is "+sal);

}
}

</pre>

The class emp implements the interfaces emplike, personlike. So the methods in those interfaces can be implemented by emp class.This provides the functionality of multiple inheritance even thought we are not directly inheriting from a multiple classes.In this example using java,multiple inheritance is achieved by using interfaces.

<h2>Implementation in C++ </h2>

The class "emp" extends "personlike" and "employeelike" classes.

<pre>
#include<iostream.h>
#include<stdio.h>
#include<string.h>
using namespace std;

class personlike
{
public:
char* name;
int age;
personlike(char* a,int b)
{
name=new char[10];
strcpy(name,a);
age=b;
}
char* getname()
{
return name;
}
int getage()
{
return age;
}
};
class employeelike
{
public:
int salary;
employeelike(int a)
{
salary=a;
}
int getsal()
{
return salary;
}
};
class emp:public personlike,public employeelike
{
public:
emp(char* a,int b,int c):personlike(a,b),employeelike(c)
{
}

};

int main()
{
emp* a=new emp("Federer",26,100000);
cout<<a->getname()<<endl;;
cout<<a->getage()<<endl;
cout<<a->getsal()<<endl;
cout<<a->name<<"\t"<<a->age<<"\t"<<a->salary<<endl;
return 0;
}
</pre>

C++ provides multiple inheritance. So class emp extends personlike and employeelike classes. Now getage(), getsal() and getname() methods can be accessed by emp class object.

<b><h3>Conclusion</h3></b>

C++ multiple inheritance can sometimes become knotted and lead to unordered hierarchy .
Java, even though is a single inheritance language can exhibit multiple inheritance using interfaces. However, care has to be taken in Java to implement all the interfaces and it can be a lengthy procedure. Ruby is unambiguous, elegant and concise.

''' <center><h2>References Used</h2></center>'''

1) The Little Book of Ruby
http://www.sapphiresteel.com/The-Little-Book-Of-Ruby

2) Programming Ruby: The Pragmatic Programmer’s guide
http://www.rubycentral.com/pickaxe/tut_modules.html

3) Bowler Ruby
http://www.softwaresummit.com/2006/speakers/BowlerRubyForJavaProgrammers.pdf

CSC/ECE 517 Fall 2007/wiki1 6 c9

2007-09-20T01:08:58Z

Spinnam:

<b><center>Topic 6: Mixins</center></b>

Compare the use of Ruby mixins with how one would solve the same problem in Java or C++. In Java, you might use interfaces or the
decorator pattern (p. 91 of Head-First Design Patterns). In C++, you would probably use multiple inheritance. Give code in all
three languages and compare the solutions on the basis of verbosity and elegance.

<h2>Inheritance and Mixins</h2>

Some object-oriented languages (notably C++) support multiple inheritance, where a class can have more than one immediate parent, inheriting functionality from each. Although powerful, this technique can be dangerous, as the inheritance hierarchy can become ambiguous.
Ruby offers an interesting and powerful compromise, giving you the simplicity of single inheritance and the power of multiple inheritance. A Ruby class can have only one direct parent (i.e no class can inherit from more than one class) and so Ruby is a single-inheritance language. In cases where you want numerous extra behaviors for a class’s instances, Ruby classes provide the multiple inheritance functionality by using mixins. You can use include any number of mixins (a mixin is like a partial class definition). This provides a controlled multiple-inheritance-like capability with none of the drawbacks.

<h3> Mixins </h3>

The process of including a module in a class is also called ‘mixing in’ the
module – which explains why included modules are often called ‘mixins’.
An object can access the instance methods of a module just by including that
module using the include method.

There are two major features that classes possess but that modules do not: instances and inheritance. Classes can have instances (objects), superclasses (parents) and subclasses (children); modules can have none of these.

<h4>Sample</h4>
<pre>
module SampleMixin
def do_something
puts “doing something”
end
end

class SampleClass
include SampleMixin
end

s=SampleClass.new
s.do_something
</pre>

<h2>Include </h2>

A couple of points about the ''include'' statement. It has nothing to do with files. C programmers use a preprocessor directive called #include to insert the contents of one file into another during compilation. The Ruby ''include'' statement simply makes a reference to a named module. If that module is in a separate file, you must use require to drag that file in before using ''include''. Second, a Ruby include does not simply copy the module's instance methods into the class. Instead, it makes a reference from the class to the included module. If multiple classes include that module, they'll all point to the same thing. If you change the definition of a method within a module, even while your program is running, all classes that include that module will exhibit the new behavior.

<h3>Including Modules From Files</h3>

Often it is more useful to define modules in separate files and include them as needed. The first thing you have to do in order to use code from another file is to load that file using the require method, like this:
require( "testmod.rb" )

The required file must be in the current directory, on the search path or in a folder listed in the predefined array variable $:. You can add a directory to this array variable using the usual array-append method, << in this way:
$: << "C:/mydir"
The require method returns a true value if the specified file is successfully loaded; otherwise it returns false. If in doubt, you can simply display the result:
puts(require( "testmod.rb" ))

Pre-Defined Modules

The following modules are built in to the Ruby interpreter:
Comparable, Enumerable, FileTest, GC, Kernel, Math, ObjectSpace, Precision, Process, Signal

<center><h2>EXAMPLE</h2></center>

Consider a scenario of an employee. An employee has the features of a person ( having name,age and other attributes) and also that of an employee( having salary, hours of work and other attributes). In our example, we explain multiple inheritance by showing how modules "Emplike" and "Personlike" are inherited by "Employee" class. Thus we illustrate mixins in ruby.

'''Implementation in Ruby '''
<pre>
module Personlike
attr_accessor :name
attr_accessor :age
def getname
return "#{name}"
end
def getage
return "#{age}"
end
end

module Emplike
attr_accessor :salary
def getsalary
return "#{salary}"
end
end

class Employee
include Personlike
include Emplike
end

s=Employee.new
s.name="Federer"
s.age=26
s.salary=100000
puts (s.getname)
puts(s.getage)
puts(s.getsalary)

Output:
Federer
26
100000
</pre>

<b><h3>Disadvantages of Mixins in Ruby</h3></b>

A mixin will not warn if the mixin and the user define the same method.(i.e if there are methods with same name in mixin and also in the class, the method in the class is executed without warning the user).

Consider the above example: Incase we include a getsalary method in both the module and also in the class, the method in the class is executed without warning.

<pre>
module Emplike
attr_accessor :salary
def getsalary
return "#{salary}"
end
end

class Employee
include Personlike
include Emplike
def getsalary
return" This is the salary of user defined getsalary"
end
end

s=Employee.new
s.salary=100000
puts(s.getsalary)

Output:
This is the salary of user defined getsalary

</pre>

<h2>Implementation in Java</h2>

The class "emp" implements "emplike" and "personlike" packages in this example.

<pre>
package assignment;

public interface personlike {
String getname();
int getage();
}

package assignment;

public interface emplike {
float getsalary();
}

package assignment;

public class emp implements assignment.emplike,assignment.personlike
{
String name1;
int age1;
float salary1;
emp(String name,int age,float salary)
{
name1=name;age1=age;salary1=salary;
}
public String getname()
{
return name1;
}
public int getage()
{
return age1;
}
public float getsalary()
{
return salary1;
}
}

package assignment;

public class emptest {

public static void main(String args[])
{
emp ob=new emp("Federer",26,100000);
String name=ob.getname();
int age=ob.getage();
float sal=ob.getsalary();
System.out.println("name is "+name+"age is "+age+"salary is "+sal);

}
}

</pre>

<h2>Implementation in C++ </h2>

The class "emp" extends "personlike" and "employeelike" classes.

<pre>
#include<iostream.h>
#include<stdio.h>
#include<string.h>
using namespace std;

class personlike
{
public:
char* name;
int age;
personlike(char* a,int b)
{
name=new char[10];
strcpy(name,a);
age=b;
}
char* getname()
{
return name;
}
int getage()
{
return age;
}
};
class employeelike
{
public:
int salary;
employeelike(int a)
{
salary=a;
}
int getsal()
{
return salary;
}
};
class emp:public personlike,public employeelike
{
public:
emp(char* a,int b,int c):personlike(a,b),employeelike(c)
{
}

};

int main()
{
emp* a=new emp("Federer",26,100000);
cout<<a->getname()<<endl;;
cout<<a->getage()<<endl;
cout<<a->getsal()<<endl;
cout<<a->name<<"\t"<<a->age<<"\t"<<a->salary<<endl;
return 0;
}
</pre>

<b><h3>Conclusion</h3></b>

C++ multiple inheritance can sometimes become knotted and lead to unordered hierarchy .
Java, even though is a single inheritance language can exhibit multiple inheritance using interfaces. However, care has to be taken in Java to implement all the interfaces and it can be a lengthy procedure. Ruby is unambiguous, elegant and concise.

''' <center><h2>References Used</h2></center>'''

1) The Little Book of Ruby
http://www.sapphiresteel.com/The-Little-Book-Of-Ruby

2) Programming Ruby: The Pragmatic Programmer’s guide
http://www.rubycentral.com/pickaxe/tut_modules.html

3) Bowler Ruby
http://www.softwaresummit.com/2006/speakers/BowlerRubyForJavaProgrammers.pdf