Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Recommenders/CleanCodeMethodSorter"

m (Plugin)
Line 18: Line 18:
 
So far, no issues documented. Please report any encountered bugs [https://bugs.eclipse.org/bugs/show_bug.cgi?id=344394 here] (suggestions are also welcome).
 
So far, no issues documented. Please report any encountered bugs [https://bugs.eclipse.org/bugs/show_bug.cgi?id=344394 here] (suggestions are also welcome).
  
==== Responsible People ====
+
==== Responsible Staff ====
 
This plugin is developed by Mateusz Parzonka as part of an university hands-on at the [http://www.stg.tu-darmstadt.de Technische Universität Darmstadt] (Germany), supervised by Marcel Bruch and Andreas Sewe.
 
This plugin is developed by Mateusz Parzonka as part of an university hands-on at the [http://www.stg.tu-darmstadt.de Technische Universität Darmstadt] (Germany), supervised by Marcel Bruch and Andreas Sewe.
  

Revision as of 18:43, 21 August 2011

Plugin

Currently BETA-stadium (Build 101, 08/22/2011). Features and description are subject to change.

Description

The Clean Code Method Sorter is a lightweight plugin for the Eclipse Platform. It provides techniques to sort methods in Java-classes, aiming to increase the readability of the source code.

Methods are reordered following the news-paper-metaphor conceived by Robert C. Martin in his book "Clean Code": A class should be readable like a newspaper, with the most important methods being at the beginning of the class, followed by methods which are invoked later in the execution flow.

Further organisation possibilities are provided by method clustering according to:

  • access level
  • method name (aka overloaded methods)
  • being accessors of the same field (aka getters and setters).

Installation Instructions

Please download and install the plugin using the update-site.

Bugs

So far, no issues documented. Please report any encountered bugs here (suggestions are also welcome).

Responsible Staff

This plugin is developed by Mateusz Parzonka as part of an university hands-on at the Technische Universität Darmstadt (Germany), supervised by Marcel Bruch and Andreas Sewe.

User-Interface

The plugin mainly provides a "Sort Methods..."-Operation which can be triggered from different point in the GUI.

Processing of individual Java-classes

When a Java-class is opened in the Java Editor, the source menu should be visible in the main menu bar. The plugin augments the import-group in the source menu with a command labeled "Sort methods…". Triggering this command lets the Clean Code Method Sorter sort the methods in this class.

Per default, the command is bound to the keybinding "Option-S" (Mac) or "alt-S" (other platforms). User-defined keybindings are possible: Search for the command "Sort methods…" in the "Clean Code"-category in the keys-preferences-menu.

SourceMenu.jpg

Processing of multiple Java-classes

When selecting Java-specific content in the Package Explorer a right mouse-click (context-click) activates the associated pop-up-menu. In the Java-context, a source-submenu is visible. The plugin augments the import-group in this menu with the command labeled "Sort methods…", which will sort all methods in selected objects and their child-objects upon triggering.

"Sort methods…" can be called on any selection of

  • Java-projects
  • source folders
  • packages
  • compilation units (Java-files).

After successful sorting, a message will appear showing the number of processed classes.

In the beta-phase an additional command "Shuffle methods randomly…" may be available which shuffles methods randomly to enable easier evaluation of the method sorter.

PulldownMenu.jpg 

Preferences

Invocation start-point strategy

Following the news-paper-metaphor the invocation-relation between methods is one of the strongest clues to derive a method ordering. Since classes usually offer some interface callable by clients, the invocation chain(s) can begin from several points. The user can select two different strategies to priorize the invocation start points:

  • Use existing order: Methods which are found at the beginning of the class are used as start points first. Useful, when beginning of the class (e.g. the public interface) is ordered acceptably.
  • Apply heuristic: A working list of start-points is calculated exploiting a multitude of clues:
    • Separation of "roots" and "leafs" in the invocation graph
    • access level
    • number of callees
    • method name (lexical ordering)
Invocation ordering strategy in method bodies

A method can have multiple invocations in its body. This leaves us two possibilities to traverse the invocation graph to derive a method ordering: We can go "deep" by entering each method we encounter and processing the methods there, or we can go "broad" by processing all methods in the body before going to a lower level in the invocation tree.

When deriving a method ordering from the order of invocations,

  • Breadth-first: Ordering is following a breadth-first-search approach in the invocation graph.
  • Depth-first: Ordering is following a depth-first-search approach in the invocation graph.

Which setting is better is a matter of taste. Depth-first is set as default, since it seemed be more consistent with the original description by Robert Martin and due to feedback of beta-testing users. (Discussion about the ordering strategy is welcome).

Cluster getter and setters

The user can activate the clustering of getter and setters denoting pairs of methods where the methods:

  • Start with "get" and "set"
  • Have the same suffix after "get" and "set"
  • The return type of the potential getter fits the parameter-type of the potential setter (which has an arity of 1)

The clustered methods form a subgraph which is ordered using the same parameters like its supergraph (except applying clustering).

Cluster overloaded methods

The user can cluster overloaded methods which are methods that have the same name but have different parameters. Overloaded method clusters are handled as subgraphs and sorted individually.

Cluster access levels

When activated, methods are clustered according to their access. Note that each access level is not handled as a subgraph: The clustering is applied "post-hoc".

Respect before/after-relationship

When set to true, the sorting algorithm tries to find an ordering where methods are ordered before methods following in the invocation chain. What is the difference to pure invocation ordering, you may ask? To traverse call chains you have to select start points. As a result some start point p may be entered after a method m is called by p yielding an ordering of p-after-m, which may be not desired. This option corrects this behaviour.

A more technical description: A method a is said to be before method b, when b is after a in some point of the chain of invocations. The relationship can be expressed in terms of reachability in invocation graphs. Note that because of cyclicity in invocation graphs a method a can be before a method b and vice versa. When the relationship is respected, these properties hold:

  • a is before b and b is not before a : a will be sorted before b
  • a is before b and b is before a : Cyclicity, a and b will be ordered by invocation order only
  • a is not before b and b is not before a : Non-reachability, a and b will be ordered by invocation order only

This setting defaults to true, because it seems to yield intuitively convincing results. Discussions are - of course- welcome.

Back to the top