April | 2013 | Java Deep

I was reading the article
The Golden Rules of Code Documentation and I thought to give an example of how I handle the situation expressed there using the following sentence:

If you need comments to clarify code, better think how to write code differently, so it is more understandable. You do not need yet another language (comments) to mess with the primary language (code).

The referenced article argues with the statement above even letting personal feelings out:

Quite obviously, this person has written 1-2 “Hello world” applications, where this obviously holds true.

I felt touched, since I totally agree with the statement quoted first and at the same time I strongly believe that after 25 years of programming I can not be categorized as a “hello word” programmer. Those who do not know me: I wrote ScriptBasic (C language), Jamal (Perl), jScriptBasic (Java) to mention an excerpt from the few OS projects I was heavily involved in. I can mention but not list the codes I created professionally to feed myself and family for different banks, telcos and honey water companies.

To proof his point, the author of the before mentioned article says:

How would you write this business logic down into code, such that you can live without comments?

A stock exchange order of clearing type code 27 needs to be grouped with all other subsequent orders of type code 27 (if and only if they have a rounding lot below 0.01), before actually unloading them within a time-frame of at most 35 seconds (fictional example in a real-life application).

I had three thoughts:

Challenge accepted (first instinct, usually stupid)
The text in the quoted quote was about comments between the lines of the code and not the JavaDoc and not even the documentation of the project. The requirement text given as an example is by no means to be put into the code. That is a requirement.
Nothing heals badly formatted requirements like the sample given above. Never mind, that is not a real spec. only an example. Forget this last comment, I do not want to open flame war on this. There is enough battlefield elsewhere.

The rest of the referenced article talks about documentation and if I replace the word “comment” with “documentation” in the text I can generally be agreeable with that.

But lets have a look at the fun part! Read again the “spec” above and have a look at the code:

package stock;

public class StockExchangeOrderUploader implements Runnable {

	private final StockExchangeOrderSource source;

	public StockExchangeOrderUploader(StockExchangeOrderSource source) {
		this.source = source;
	}

	private StockExchangeOrderGroup pendingGroup = null;

	public void setPendingGroup(StockExchangeOrderGroup group) {
		pendingGroup = group;
	}

	@Override
	public void run() {
		while (source.hasNext()) {
			final StockExchangeOrder order = source.next();
			if (order.isBelowRoundingLotLimit() && order.isOfClearingType27()) {
				if (There.isA(pendingGroup)
						.whichWasStartedNotSoonerThan35SecondsBeforeThis(order)) {
					Add.the(order).toThe(pendingGroup);
				} else {
					if (There.isAny(pendingGroup)) {
						Upload.the(pendingGroup);
					}
					Add.the(order).toThe(pendingGroup);
				}
			}else{
				Upload.the(order);
			}
		}
		if( There.isAny(pendingGroup)){
			Upload.the(pendingGroup);
		}
	}

}

Do you feel the need to put any comment between the lines? Do you need anything?

Oh…. jah.. sorry. Perhaps the other interfaces and classes:

https://github.com/verhas/commentOrNotToComment