Design – Generic code or code easy to understand

designprogramming practices

At work now I had an argument with co-worker, because I made a page that he feels is too generic.

The page has 3 modes (simple, adv and special) – it has to work like this, because we don't choose how the specification is written. in each mode the page looks different(the changes are not big – it shows/hides 5 text fields in different combinations based on the mode).

My co-worker think it should be 3 pages and when you change something you should just merge the changes to other two modes.

The fields now has code like rendered="#{mode!=2}", etc.

P.S. Now the difference is 5 fields, but in the future no1 know how much it will be changed.

We use Seam(JSF/Facelets), here is pseudo facelet code(to make it easier to understand). I did not put it in panelGroups to better present the problem.

<h:output rendered="mode=2" value="Name: " />
<h:input rendered="mode=2" value="bean.name" />
<h:output rendered="mode=2" value="Surename: " />
<h:input rendered="mode=2" value="bean.surname"  />

<h:output rendered="mode!=2" value="Surename: " />
<h:input rendered="mode!=2" value="bean.surname"  />
<h:output rendered="mode!=2" value="#{mode==1?'My Name':'My friends name'}" />
<h:input rendered="mode!=2" value="bean.name" />

I duplicated version it would look like this(pseudo code)

<c:if test=mode=1>
        <ui:include view=modeSimple.xhtml>
</c:if>
<c:if test=mode=2>
        <ui:include view=modeAdv.xhtml>
</c:if>
<c:if test=mode=3>
        <ui:include view=modeSpec.xhtml>
</c:if>


modeSimple.xhtml
    <h:output value="Surename: " />
    <h:input value="bean.surname"  />
    <h:output value="My Name" />
    <h:input value="bean.name" />
modeAdv.xhtml
    <h:output value="Name: " />
    <h:input value="bean.name" />
    <h:output value="Surename: " />
    <h:input value="bean.surname"  />
modeSpec.xhtml
    <h:output value="Surename: " />
    <h:input value="bean.surname"  />
    <h:output value="My friends name" />
    <h:input value="bean.name" />

Best Answer

You should structure your templates using the same rules as when programming. This essentially means extracting common design elements into separate files to avoid duplication, and thus achieve more reusable design. That is rule #1 (DRY) and the method is called refactoring in programming terms.

The second rule is that you should strive for simplicity and clarity. It should be easy to understand the layout and where to go when to you need to change things.

Following the first rule to the letter leads to heavy decomposition of your gui into lots and lots of small snippets which can make it hard to understand how the layout is created. You have to hunt around a lot to find where things are. This violates the second rule, so you need to find a balance between these two opposites.

But the best approach is to find a solution that avoids this issue completely. I think, in this case, you should consider a simpler approach altogether. I assume this is HTML and you mention "simple and advanced" states in the GUI. Have you considered always generating all fields and then handle the GUI logic in JavaScript? In other words, write client-side code which hides and shows the relevant fields on the fly depending on which mode (state) it is in?

This also has the benefit of being able to switch mode on demand without involving the server and you don't have to compromise any of the rules. Another great thing is that you can let the front-end guys do these changes without having to involve the back-end programmers who usually are not that overly keen on spending time tweaking and polishing the design and interaction.

Related Topic