RESOURCE: Code Smells and more (Design Patterns, Anti-Patterns and Refactoring Tips)

One interesting reference guide to design patterns (and anti-patterns) as well as "code smells" (who happen when the code you're touching smells like a rotten bird in your garden) is: 

• https://sourcemaking.com/design_patterns (Design Patterns: structural and more; also remember to avoid anti-patterns)
• https://sourcemaking.com/refactoring (code smells: what to do to improve this "code smell"?)

Nice readings. 

RESOURCE: Security is a Process

Security is a process: It is not just a tool to produce you reports on potential holes (when probably you don't have the time or the skilled persons to browse through the detailed report it generates).

And this is what happens when you don't have the process in place. You will get to the cover page in the news (for the bad reasons):
https://www.publico.pt/portugal/jornal/auditoria-detectou-21-falhas-de-seguranca-no-sistema-informatico-dos-tribunais-21474798

Excellent initiatives at this level (security) are government initiatives like these ones:

• https://en.wikipedia.org/wiki/Cyber_Essentials (UK)
• https://web.nvd.nist.gov/view/ncp/repository (US, from the NIST)
• https://nvd.nist.gov/ncp/repository (the checklists)
• http://www.usccu.us/documents/US-CCU%20Cyber-Security%20Check%20List%202007.pdf (2007, US)

Tools: (INTERNAL):

1. At the "SW and Security Product Assurance technical area" a list of recommended tools can be found and some are security-related: https://delivery.critical.pt/TechAreas/sspa/SitePages/Web%20Application%20Security%20Testing.aspx (accessible from https://delivery.critical.pt/TechAreas/sspa/SitePages/Tools.aspx)
2. Security Testing Tool Example: IBM AppScan: Used to perform automated web application security tests (dynamic). IBM Security AppScan Standard helps decrease the likelihood of web application attacks and costly data breaches by automating application security vulnerability testing. IBM Security AppScan Standard can be used to reduce risk by permitting you to test applications prior to deployment and for ongoing risk assessment in production environments. 

Remember: Your information system is as strong as its weakest link. For instance: If you don't patch your system components that you rely upon (e.g. your RDBMS, Application Servers, File Servers, Web Servers, target Operating Systems) who do you think your customer will turn to when a security flaw turns up?

History: 2017-11-30, updated with SSPA internal resources (and IBM Appscan tool).

TOOLS: Rapid prototyping tools (for mockups creation as well as live feature navigation)

The basic tool for rapid prototyping is, as you might know, a white board and good User eXperience Design (UXD) principles (in your head).

Your favorite IDE could serve the purpose (you already know how to implement Grahical User Interfaces there, so there's no ramp up). Sparx Systems' Enterprise Architect also allows you some basic prototyping (and navigation) with the advantage of traceability of UI elements to other elements of the model (such as requirements and tests).
Any image editor also could do (as well as some sheets of hand-drawn papers that after peer review could be quickly scanned and added to the Version Control System or to meeting minutes). The only problem with these latter tools is the need of navigation (between windows, pages) so that the visualization of the final system behavior is easier.

There are however specialized tools for rapid prototyping like Balsamiq. Some are free, some other are not. Some are specialized for Web applications, some for mobile apps, some for client apps.

A good review of some of these tools can be found here:

• http://adaptivepath.org/ideas/rapid-prototyping-tools-revisited/
• https://docs.google.com/spreadsheets/d/1iyTUtVWFSGyJwRRizafhh3B3KX4kh-fc7mwhwfg7D8o/pub?output=html

Software Design: Architecture Specification

Architecture Specification (activity) consists of mainly 3 sub-activities:

1. Define Meta-Architecture Options: Principles, Style, Key Mechanisms; also: select key technologies; specify architectural guidebooks and standards (or identify the external ones to be reused); key mechanisms: coupling control strategy (layers), OOP approach, n-tier approach, layer comm., authentication, authorization, data editing strat., data id. strat., error handling, etc.) 
2. Define Conceptual Architecture: Partition of the system, allocate responsibilities; On some guidance on how to perform the partition of the system (into subsystems / modules) read more at: http://silvaonsoftware.blogspot.com/2016/05/software-design-design-principles-and.html 
3. Define Logical Architecture: Model collaborations, design interfaces

Additional Info on the SW Design Process

The SW Design Process has these 3 main tasks:

1. Architectural Requirements Sub-Activity: Establish architectural relevant requirements - org./functional/non-functional - and this implies: Establish org. goals and constraints, review functional requirements (complement with use cases), review non-functional requirements (associate measurable qualities with use cases) 
2. Architecture Specification Sub-Activity: (this topic)
3. Architecture Validation Sub-Activity: Includes Architecture Peer Reviews, Brainstorming Key Decisions, Reuse, Traceability Matrices.

Further information can be found on your "favorite QMS" and here:
Visual Architecting Process (Web version and PDF).

Software Design: Design Principles (and how they could help us in partitioning the system)

With a good decomposition (into modules and submodules):

• The overall system Design is improved (anticipating and solving earlier performance or scalability bottlenecks, better preparation for change and evolution, etc.) and... 
• It is easier to maintain (Maintainability) as well as... 
• It easier to Develop (during the following activities of software construction: easier to split tasks between developers, easier to integrate new technologies and new team members, easier to forecast the impact of new requirements with good accuracy, etc.). 

But how exactly should it be performed? For some principles, jump here (*).

CHANGE IS PART OF LIFE: So we should design systems that cope with it "elegantly"
- The customer can change it's mind
- The market needs can change during the project (with impact on our scope)
- We could have got requirements wrong and have the need to rework them (as well as all dependencies on them, etc.)
- Reused components could have to be replaced (due to lack of support, stability, etc.) along the way
- etc.

Modules

A module can be defined variously, but generally must be a component of a larger system, and operate within that system more or less independently from the operations of the other components of the system. A module is a subdivision of complexity that has evident benefits.

Decomposition Levels

• The first partition shall be determined by selection or design of an Architectural Archetype (system type, e.g. Web App)

• The archetype establishes tier and layer separation and, in the physical tier perspective, a clear and unavoidable packaging and coupling isolation criterion.

• The archetype is a structural technical view of the solution regardless of business domain and particularities. As such, it is a very stable and reusable specification.

• The archetype is also a technological determinant decision as it clearly points to the usage of specific technologies, frameworks, development environments, etc.

• The second level partition shall address decomposition of the archetype’s parts into Package Components (UML Package Diagrams; package = namespaces that group classes and interfaces)

• The Packaging Components represent the binary outputs of the solution (in .Net for instance these correspond to the .EXE and .DLL)

• Their decomposition criteria are based on coupling, deployment and tier placement.

• The Packaging Component represents a single reference point for the functionality and is an aggregation for further decomposition (Component).

• The third level partition shall address decomposition of the Package Components into Components and Interfaces and establish third-party dependencies (reuse process) - UML Component Diagrams

• Remember that Components may be nested into each other to produce sub-levels of decomposition and reduce complexity of the overviews.

• This is a pure conceptual view that is not directly concerned with packaging and deployment.

• This view is oriented by “information-hiding” in Parnas sense. The goal here is to represent the system with as few major concepts as possible. Of course each of those concepts may be further detailed (by sub-components) as needed.

• The fourth level partition shall address Component decomposition in Classes - Detailed Design; physical data tables could be also modeled (it the system is database-oriented) and traced to classes.

All elements of the decomposition should trace to the upper level elements they are related to (traceability) in the analysis model.

Principles for module decomposition 

• Strong cohesion and loose coupling (goals to be achieved): 

• Cohesion is a measure of how strongly related and focused the responsibilities of a single module are. That is, how homogeneous and simple is the goal of a software module.

• Coupling (or dependency) is the degree to which each program module depends on each other module.

• Package Cohesion Principles: Classes are a necessary, but insufficient, means of organizing a design. The larger granularity of packages is needed to help bring order. But how do we choose which classes belong in which packages

• Release Reuse Equivalency Principle: The granule of reuse is the granule of release (and that should be the package).

• Common Closure Principle: Classes that change together, belong together.

• Common Reuse Principle: Classes that aren’t reused together should not be grouped together.

• Package Coupling Principles: Applications tend to be large networks of interrelated packages. The rules that govern these interrelationship are some of the most important rules in object oriented architecture

• Acyclic Dependencies Principle: The dependencies between packages must not form cycles.

• Stable Dependencies Principle: Depend in the direction of stability.

• Stable Abstractions Principle: Stable packages should be abstract packages.

Architectural Principles

• Abstraction gears towards comprehension
• Encapsulation gears towards protection from outside interference
• Information Hiding gears towards containment of design changes
• Open Closed Principle – OCP: “A module should be open for extension but closed for modification.” i.e. “We should write our modules so that they can be extended, without requiring them to be modified. In other words, we want to be able to change what the modules do, without changing the source code of the modules.”
• Inversion of Control (or Dependency Inversion Principle) is an important object-oriented programming principle that can be used to reduce coupling inherent in computer programs: “Depend upon Abstractions. Do not depend upon concretions.” [Martin]
• Interface Segregation Principle – ISP: “Many client specific interfaces are better than one general purpose interface” i.e. “If you have a class that has several clients, rather than loading the class with all the methods that the clients need, create specific interfaces for each client and multiply inherit them into the class.” [Martin]

Along with OOP Principles, some Design Patterns (which is a well known, very good solution for a recurrent problem) are also very useful while performing the decomposition of a system.

(*) Additional References and Further Reading

• http://ifacethoughts.net/2006/03/24/design-principles/ (REP, DBC, etc.)
• http://ifacethoughts.net/2006/04/04/reuserelease-equivalency-principle/ (REP)
• https://sourcemaking.com/design_patterns (Design Patterns: structural and more - creational and behavioral; also remember to avoid anti-patterns)
• https://sourcemaking.com/refactoring (code smells: what to do to improve this "code smell"?)
• Design Principles and Design Patterns - Robert C. Martin - 2000
• OOP principles (if you're using OO Languages): Abstraction, Encapsulation, Information Hiding
• Additional Source: ITG M. and Uncle Google giving us the above cited results.

Also remember to learn - at a second stage - about:

• Database Design Patterns, 
• GUI Design Patterns (and UXD - User interaction), 
• Enterprise Architecture Patterns (Integration), 
• etc.

(2016-05-12: Added link for enterprise integration patterns; 2016-07-21: formatting, typos)

Process: SW Design Process and its main work products

After SW Requirements (and the SW Requirements Engineering Phases ends successfully) we'll be applying the next QMS Process: ENG.2 SW Design Process. The main goal is to define "how to do" things (requirements were focused on "what to do").

Typically all design decisions (high-level-design) are written on the Software Architecture Specification (SAS) which is commonly a deliverable.

The pertinent milestone is called the Critical Design Review (CDR) unless you have provided the customer with a SAS V1 on PDR. If you did so, you'll probably end the CDR with SAS V2. If not you'll be releasing a SAS V1 apar with the code (and the binaries needed for deploying the system on a testing environment, for the next phase, the Validation Phase).
In some QMSs, some part of the design and the code are performed in the same phase (so that if you spot a need to change de design during the code, you are still able to change it).

Other Design Documents

Sometimes customers will ask for a Software Detailed Design (SDD is a kind of a programmer's manual that describes all source files contents including for an OOP language all classes, including data members, operations, interfaces and the algorithms being implemented in those source files). If possible, align the team with the proper coding conventions and comments to be produced aling the code, in order to be possible to reverse engineer te code to a modelling tool (that enables you to build in a faster way the SDD document). Sometimes this document is called Detailed Design Description.

There are also special documents called Interface Control Documents (ICD) that come specially handy when you need to establish communications (data flows in and out) with external systems. These could be described in a section in the SAS, or sent to a separated ICD document (if you want to share just the interface control part to external departments and/or companies).

Database specification documents (DBS) are also considered detailed design documents and are typically generated from data modelling tools (or reversed engineered to a model and then to a document) for publication (to the customer, to the developer/maintenance teams).

This is where you want to define key technologies to use (what DB Server, what Application Server, what OS) up to the version if needed and the last great opportunity to think on reuse (COTS components, open source components, in-house components, etc.)

Main Activities (SW Design)

Mainly we'll be doing:

• Architectural requirements (completing the requirements catalog with non-functional - or other organizational and even functional - requirements); Architectural Requirements are a subset of the user, system and software requirements, determined by architectural relevance.
• Architecture specification:
• Defining the meta-architecture options: principle, style, key-mechanisms 
• Defining the conceptual architecture: Partition system, allocate responsibilities
• Defining the logical architecture: Model collaborations, design interfaces
• Architecture Validation: As in all things in life, we'll be peer reviewing the SAS document, and before that, we'll be brain-storming key decisions and thinking on Reuse (remember to use DAR).

You can find the process definition here.
For a good online resource on architecting remember to look at the The Visual Architecting Process (VAP, by Ruth Malan and Dana Bredemeyer, 2002)