What’s in a Name: Transparency

Photo from [Flickr](https://www.flickr.com/photos/piratenmensch/9702440183/)
Photo from Flickr

Another post to clarify a misused term, this time I’ll cover transparency.

Some developers use transparency to denote abstractions, in the sense of “things are not visible any longer”. For example, people tell me, “this fancy framework (like CORBA) makes network issues transparent and abstracts them away for me”. See the following sketch:

Framework hiding Network from Developer
Framework hiding Network from Developer

The framework hides network details from the developer, so it makes certain details of networking invisible. People call this “transparent”, although it means the opposite!

Transparency

Transparency (from latin trans: through and parere: follow) means “light can pass through”. In former times, a “transparency” was a usually rectangular piece of translucent plastic which people used for overhead projection (in case you don’t know that word, you’re propably still young…)

Transparency is often used to denote openness, free sharing and distribution of knowledge or information. There’s even a multinational non-governmental organization called Transparency International, which associates transparency with the absence of corruption.

Good Uses of Transparency

In many cases, transparency in this sense of openness is a positive or indispensable quality of arbitrary systems.

In my opinion, a certain amount of transparency is absolutely required within governments and other organizations to prevent malicious behavior. On the other hand, every organization needs to have an appropriate amount of privacy (oh oh, one of these nasty and difficult tradeoffs again…)

Too Much Transparency Can Hurt

Let’s come back to software: When discussing architectures, it can be really helpful to rely on abstractions, to hide certain details.

As an example, the context view of systems provides a great overview of external interfaces, without revealing any internal details of the system under discussion. See the diagram below for in informal example.

Context View of a System
Context View of a System

When discussing architectural structures, you often want to hide details, refrain from divulging the inner workings of some parts of your system. You practice information hiding, using blackboxes to reduce detail and (hopefully) improve overview and understanding.

Too much transparency can really hurt in such cases - potentially overloading people with information they currently don’t need or want.

Let’s try to add (too much) transparency to the context diagram from above:

Overly Transparent Context View of a System
Overly Transparent Context View of a System

When I encounter such diagrams in architecture discussions or documentation, I try to reduce transparency by creating abstractions. I look for elements that can be cohesively grouped together into a blackbox - adding opaqueness.

Opaqueness

Opaqueness is the opposite of transparency: Opaque things do not let people peek inside, they do not let light pass through. They’re closed, not open.

It’s really bad to have (too much) opaqueness in governments or organizations, but it’s often good to have appropriate opaqueness in systems - as people usually need to focus on certain details instead of the ultimately_complete_ set of details.

To come back to the network example from the beginning: Frameworks abstracting away the network usually fail (Joel Spolsky explained that in his classical Leaky Abstractions blogpost).

Whitebox versus Blackbox

White- and blackboxes help you apply structural transparency.

As software developer or -architect you should use black- and whiteboxes in your discussion and documentation of systems. Both will be useful for you:

Structural transparency is one form of architectural transparency, which also covers conceptual transparency.

For example, if you discuss your rather complicated domain model in a joint workshop with developers and business people, you likely want to keep technical details (aka concepts) of your persistence mechanism (e.g. your database query optimizer configuration, storage array RAID level, ext3 vs ext2 file system…) opaque (hidden) from this discussion.

On the other hand, if you discuss performance optimization tactics within your development team, you will make exactly these kinds of details transparent (visible), but will likely hide some of your structural details.

You should therefore explicitly decide when to apply transparency (whitebox) and when to use opaqueness (blackbox). The information needs of your stakeholders provide a simple yet elegant heuristic for this decision: If somebody needs certain information, then you should use transparency. In case this information will not provide additional value, keep it opaque.

Listen to What People Mean…

Sometimes people mean different things than they say. Please be sympathetic - and try to find out what they mean (and ignore part of what they say, as my colleague Phillip Ghadir advises).

Most developers I know and work with really value transparent architectures, projects and organizations. When they say, “framework X makes Y completely transparent”, they often mean that framework X has a nice abstraction for feature Y, hides this feature in a (non-transparent, opaque) blackbox.

In this sense, the Java Persistence API (JPA) makes most of your persistence details opaque, although (very knowledgeable) people from Apache OpenJPA tell you the opposite:

“JPA makes persistence transparent to you, the developer” (quoted from their website)

Thank you…

Thanx for reading – and may you work with transparent architecture and development processes, but may your blackboxes remain opaque!

Acknowledgments

Thanx to Tammo van Lessen (who came up with the idea to this post - and made opaqueness transparent for me…), Andreas Krüger, Claudia Rauch for their friendly reviews and Piratenmensch for allowing free use of his “Transparent” photo.