Recorded at:

The Code is the Design

Sections

Architecture & Design,

Development

Topics

Source Code ,

Architecture ,

Design ,

CodepaLOUsa 2011 ,

Documentation ,

Programming

Share |

RELATED Research

1. Back to top

   Video Chopped Out

   by Gonzalo Vinas

   Fellows, around minute 26 the video cuts off. Please fix! - Thanks in advance

   Reply

2. Back to top

   Design not = source code. Design not = OO design.

   by graham berri

   Hi Mark
   
   Sure:
   Source code should be documentation that the next programmer wants and needs.
   "Software is not hardware" (name of paper bottom right of Library at avancier.co.uk.)
   TDD and Refactoring are right and proper.
   And everything you say sounds fine - except for the premise in your title.
   
   I put it to you:
   Documentatation (source code if you like) tells us what code does (its intent).
   Design tells us what shaped the logical structure of the code.
   Design tells is what decisions were made on the way to the code.
   
   I put it to you:
   Software documentation using the likes of UML is way too low level.
   We have to manage the complexity of large systems through abstraction to a much higher level.
   Documenation of the design should be 10 to 100 times more abstract than the source code.
   
   Design not = OO design
   Bob Martin likes to make fun of a UML class diagram for a 10 pin bowling game he codes using TDD. The trouble is: a class diagram is the wrong design model. The right design model for the code he codes is a simple regular expression that describes the input data stream (basically, an iterated sequence of two ball throws).
   
   P.S. TTD is typically unit test level - what about system and acceptance testing?
   
   Design documentation should record decisions like:
   - what data structures shaped the code?
   - how mamy client-server layers? what is the purpose of a layer?
   - does a client use request-reply or fire-and-forget?
   - does a server act in a blocking or non-blocking way?
   - are components stateful or stateless?
   - is request-reply by point-to-point or message broker?
   - superviser control or distributed control of procedure?
   - components are spawned by supervisors? and deleted if no proper reply?
   - which design patterns are used? and why?
   
   Trouble is: programmers learn and talk only about technologies. They no longer learn and talk about technology-independent design - as we used to 30 years ago.

   Reply

3. Back to top

   Too simplistic?

   by Kelvin Meeks

   Perhaps the premise of Mark's article is appropriate for a certain [small] scale solution...but in my experience - it is insufficient for problems of [large] scale.
   
   There are different parties with different concerns - who need access to design information at different levels of abstraction. For example:
   
   - Non-functional requirements may often be handled by strategies that are external to code. For example: often these types are concerns are addressed by processes (IT or Business, and often manual); hardware architectures that change over time - independent of software design; network architecture that changes over time - independent of software design; etc.
   
   - User Interface design is poorly documented in the code imho - and is better served by other artifacts - such as wire frames, mock-ups, etc.
   
   - Requirements traceability anyone? I shudder to think of cluttering a module of code with traceability mapping to requirements.
   
   - When dealing with external 3rd parties - you are often limited by legal or intellectual property concerns from sharing the actual source code - which begs for artifacts at a higher level of abstraction than code.
   
   I think you can get the general idea of my line of argument from these examples...

   Reply

4. Back to top

   Re: Too simplistic?

   by graham berri

   To be sure Kelvin: the design of higher level business systems, processes, use cases and user interfaces cannot be usefully expressed in code. In my reply, I was trying to say that even the design of low level systems and processes is a different animal from source code level documentation (which yes, a programmer needs).

   Reply

5. Back to top

   Re: Design not = source code. Design not = OO design.

   by He Mike

   Hi Graham,
   
   I like your lists of what should be recorded in design documentation and your thoughts on technology-independent design.
   
   But my 2 cents is that learning technologies and design is not mutually exclusive. It is not uncommon to see a project using and combining myriads of technologies to achieve a design goal esp. in distributed systems. Although, many of the times people are talking more and more about specific technologies in public. It is understandable as we need them to help tackle our problem after all.

   Reply

6. Back to top

   Re: Design not = source code. Design not = OO design.

   by graham berri

   Programmers have to learn some aspects of design - if almost by chance - while learning a technology. However, I suspect software development is very often done very poorly because programmers have not been taught general technology-independent principles of design - and do not understand a wide enough range of design options and design patterns. They press on with the limited design options that fit the technology they happen learn (as Mark's talk suggested). And for me, OO bigotry must take some of the blame.
   
   Graham at avancier.co.uk.

   Reply

7. Back to top

   Re: Design not = source code. Design not = OO design.

   by Mark Haskamp

   There's a lot to agree with here. I especially like the idea of design documentation should be 10-100 times more abstract than the source code.
   You and Kelvin both do a decent job of pointing out one of my chief struggles with the talk: it IS simplistic. One reason for that is because of the constraints of a time limit but another reason is that it reflects a large majority of projects that I've worked on over the past 30 years. The type of documentation you suggest would be useful but it seldom exists, which leads back to the code as my primary source of documentation.

   Reply

8. Back to top

   Re: Design not = source code. Design not = OO design.

   by graham berri

   Mark. Your talk is fine. Your 30 year experience is surely common. My only issue is that the title obscures the fact that design is not documentation. Sadly, programmers are no longer taught design.
   
   Graham at avancier.co.uk

   Reply