Architectural Clarity

1
Architectural Clarity
2
Efficiency in Clarity

• At the end of the day, source code is what is
  being produced
• If it is not clearly organized and written, it
  becomes very inefficient to maintain the software
• Too many defects
• Too much time to correct defects
• Too much time to add features
• Too many help desk calls
• Poor user experience (slowness, inconsistency,
  odd features, ...)
• Two types of clarity
• In-the-small
• When examining source code lines, are they clear?
• In-the-large
• Are the overall operating principles clear and
  clearly reflected in the source code organization
• Defects come when coders are unsure if their code
  works
• Clearly see it is incorrect will fix
• Clearly see it is correct it probably is

3
Code Clarity How to Achieve It?

• Need great people
• Code is unrelentingly logical will punish any
  lapse with hours of debugging
• Need attention to detail, quickness of mind,
  extreme logical thinking
• Need University-level people doing it
• Good to have great math skills
• Need great education
• Two big mistakes
• Not knowing what is going on at every level of
  the system
• Thinking operationally, not logically

4
Not Understanding Everything

• Need to understand whats going in the software.
• E.g. building a Web app using Perl. Should know
• All about the Perl language
• All about how the Perl interpreter works
• All about how Apache runs Perl programs
• All about the CGI protocol
• All about http
• All about the Apache web server
• All about Linux systems programming
• All about how the Linux OS works
• All about the underlying Pentium processor
  (machine language)
• All about how microprocessors are built from
  gates
• How a NAND gate is built from semi-conductors
• Folks who only understand whats going on at one
  level in the system will never be great.
• With this kind of understanding, coding is adding
  the final touches to a system.
• When something fails to work, no mysteries are
  involved.
• Without this confidence random attempts at
  corrections

5
The mistake of operational thinking

• Should think of programs logically, not
  operationally.
• Understand the program as a predicate transformer
• Predicate
• A logical expression that characterizes the state
  of the system
• Pre P Post
• The program transforms the pre predicate into the
  post predicate.
• Each line of the program should be thought if in
  those terms
• Each line transforms the pre condition closer and
  closer to the post condition

6
Example of logical thinking about a program

• pre-condition array has gt 5 elements
• my elementsLeftToPrint 5
• foreach my element (_at_array)
• invariant of elements printed
  elementsLeftToPrint 5
• print "elementltbrgt\n"
• elementsLeftToPrint--
• last if elementsLeftToPrint 0
• post-condition of elements printed 5

First time elementsLeftToPrint is set to 5. None
have been printed yet Therefore the invariant is
true on entry to the loop
Proven! No off-by-one errors here This kind of
thinking becomes second nature when programming A
very, very powerful tool
Can only exit the loop when elementsLeftToPrint
is 0. Combine with invariant to get
post-condition. Now prove the invariant is
always true at the top and bottom of the loop
If true at top of loop, prove true at
bottom. Each time around, 1 element is
printed Each time around elementsLeftToPrint is
decremented Therefore is re-established at the
bottom.
By induction If true firsts time, And if true
on one iteration then true on next Then invariant
is always true
7
Logical Thinking About Sub-Routines

• E.g, If thinking in this manner will ask
• What am I assuming is true before this subroutine
  is called
• COMMENT IT
• What am I guaranteeing after it is called?
• COMMENT IT
• REFERENCE EVERY PARAMETER BY NAME
• Need to be rigorous

8
Coding Standards

• Should establish local coding standards
• Dont believe you need them until you encounter a
  really odd coder!
• Basics
• Hard tabstop setting
• Indentation conventions
• Bracketing conventions
• Naming conventions
• Commenting conventions
• Max sizes for subroutines, nested indents
• Avoidance of literals
• Avoidance of cloned code

9
Attack of the Clones

• if( count 0 )
• print "lttable border'1'gtlttrgtlttdgtnone\n"
• else
• print "lttable border'1'gtlttrgtlttdgtcount\n"
• Versus
• print "lttable border1'gtlttrgtlttdgt"
• print (count0) ? none count
• print "\n"

print "lttable borderDEFAULT_BORDER'gtlttrgtlttdgt"
print (count0) ? Text(NONE)
count print "\n"
10
Cloned Code

• Laziness.
• Unwilling to re-factor the code to account for
  all cases
• Instead will take one case, copy it, and modify
  it to take into account the other case
• Leads to
• Great difficulty in further cleaning up the code
• Must change many places
• Bugs appearing in multiple places
• Features needing to be implemented in many places
• Lack of separation of concerns
• E.g., gui, logic, database

11
Architecture

• Creating and preserving the architectural
  integrity of software is
• Important
• Difficult to do

12
Preserving Architecture

• Ensure 1 person is in charge of it
• Ensure they write it down
• Impose an architecture tax on release capacity
• Give estimates for features that include
  preserving and even enhancing the architecture

13
Architecture Definition

• A software architecture is the structure (or
  structures) of a system,which comprise
• software components,
• the externally visible properties of those
  components,
• and the relationships among them.

14
Components Structures

• Architecture defines components
• an abstraction
• suppresses details not pertinent to its
  interactions with other components
• An architecture comprises more than one structure
• modular structure (calls/uses)
• process structure (invokes, communicates with,
  synchronises with)
• physical structure (libraries, DLLs, processors)
• inheritance structures (inherits)

15
In Practice

• Three levels
• System-Level Architecture
• Programming-Level Design
• Programming Language Code
• User Interface
• Sometimes also referred to as design (or even
  architecture)
• Different topic. Not covered in this course.

16
Design Architecture in the Development Process
17
Software Architecture

• Specifying at the highest level the construction
  of the system
• Technology choices
• Platforms, language, database, middleware,
• System construction
• Overall pattern Monolithic, RDBMS,
  client/server, 3-tiered, n-tiered, distributed,
• Hardware interfaces (if any)
• Division into programs
• E.g. a program for data entry, another for data
  analysis, a Web-oriented interface,
• Division of programs into major subsystems
• Reuse strategy (shared subsystems)
• Calls constraints
• Major strategies (e.g., for persistence, IPC, )

18
Software Design

• We are now considering how to lay down code.
• E.g., Object-Oriented
• What classes? What inheritance amongst the
  classes?
• What classes will call what other classes?
• How are classes grouped into subsystems (e.g.
  Java packages)?
• What data members of classes
• Must decide these things at some point during the
  coding process.
• Wish to minimize re-writes now and down the line
• Danger in early over-complexity (c.f. Extreme
  Programming)

19
Architecture Design

• Architecture
• High-level
• Major decisions
• Not even thinking about programming
• Design
• Laying out the programming language code used
  to implement the architecture
• Organizing programming language concepts
• Coding
• Implementing the design using a programming
  language
• But, N.B. no standard terminology

20
Documentation of an Architecture

• Golden Rule of Software Development
• If its not reviewable (written down), it doesnt
  exist.
• Architectures sometime suffer from over-elaborate
  documentation
• Unnecessary. Simply document your decisions.
• Most systems dont deserve elaborate
  architectural documentation
• Dealing with unknowns
• Indicate they are unknown for the present
• Cycle back later and add new decisions taken
• But beware of costs of postponing decisions
• Must religiously keep architecture document
  up-to-date
• Very hard to do in practice takes effort
• Therefore keep it simple as possible (but no
  simpler)

21
How do we describe an architecture?

• What is the nature of the components?
• What is the nature of the links?
• Does the layout have any significance?
• How does it operate at runtime
• Dataflow
• Control flow
• Can we evaluate this architecture?

Must Be Clear!
22
Two Main Architectural Structures

• Modular structure
• Purely static
• Disappears at run-time
• Structures that survive through execution
• E.g., pipes, processes, networks, objects,
• Both views need to be considered (not the same)

23
The Essence of the Architecture Document

• Imagine after the system has been built
  attempting to describe as cogently and in as
  compact a form as possible how the system has
  been put together.
• Be utterly clear
• you only have an hour in which to do it.
• your target audience is knowledgeable
  professionals in the field, but unfamiliar with
  the domain.
• They will wish to evaluate your choices

24
Why is architecture important?

• Manifests early design decision
• most difficult to get correct and hardest to
  change
• defines constraints on the implementation
• inhibits or enables quality attributes
• Defines a work-breakdown structure
• organization (especially important for
  long-distance development)
• estimation
• architecture document provides the vocabulary
• A vehicle for stakeholder communication
• an architecture is the earliest artefact that
  enables the priorities among competing concerns
  to be analysed
• Reviewable
• architectural errors are vastly more expensive to
  fix once a system has been coded
• Can serve as a basis for training new developers
• As an indication of progress