Stephen A. Fuqua (saf)

a Bahá'í, software engineer, and nature lover in Austin, Texas, USA

Be Coherent

Hypothesis: at the beginning of their careers (and perhaps well into them), most software developers think written/verbal language skills are of little importance to their field. To the contrary: as with most science and engineering fields, where language arts and communications classes are seen as secondary at best, the truth is that communication skills are critical to success. Being “coherent” means that one is able to express himself in clear terms, logically and consistently. This ability is essential in both code and “regular” language.


Software development is the art of producing tools that help people fulfill an aspiration. It succeeds when they succeed - and it cannot succeed if the programmer is not in regular, meaningful conversation with the user (or a well-informed proxy). If someone is developing back-end or middle-tier code, then the user is the front-end developer, and the advice still applies. Communication needs to be as clear — and concise — as possible in order to move forward with a unified vision.

This kind of communication takes so many different forms… documentation, e-mails, quick conversations, dedicated meetings. Yes, there’s the dreaded ‘d’ word again: documentation. In Agile development we still (usually) need some kind of documentation, whether to help the end user learn the application or to help technical support troubleshoot issues as they arise.


Write code that is logical, consistent, and well ordered. In other words, utilize basic design principles and patterns - high cohesion, low coupling, short methods (max 100 lines?), readable / self-documenting names, etc . Avoid spaghetti code; even languages with full support for methods and classes can suffer when those methods are large, poorly described, and stitched together in a haphazard fashion. Why? Because these all make it easier for the next person — even if it is you — to maintain the code. And, it makes it easier for you to avoid bugs during initial development.

Unifying the Two

Although on the surface these two forms of communication — “plain English” (Spanish, Tagalog, etc) and code — seem very different, this coherence principle shows us strong parallels between them. Do not repeat yourself, in its essence, applies equally in regular written (less so spoken) communication as in code. Curly’s Law: Do One Thing is helpful in code, and helpful in writing. After all, you don’t want a paragraph, or its verbal equivalent, covering multiple subjects at once. That’s just a variation on cohesion; well expressed thoughts should be logically grouped together, with clear transitions from one subject to another. Again, that is true of both code and verbal/written language. And so on it goes.



  • The Mythical Man-Month, particularly chapter 7, _Why Did the Tower of Babel Fail?_
    Where did they lack? In two respects — communication, and its consequent, organization. They were unable to talk with each other; hence they could not coordinate. When coordination failed, work ground to a halt. Reading between the lines we gather that lack of communication led to disputes, bad feelings, and group jealousies. Shortly the clans began to move apart, preferring isolation to wrangling.
  • Clean Code: A Handbook of Agile Software Craftsmanship
  • Code Complete, part VII in general, section 33.5 in particular.


Posted with : Tech, Software Development Life Cycle, Meta