3

I am a relatively new developer in a small business (a team of 3 developers and an equally small QA branch) working on a medium-sized system. The current iteration is still under 100k lines of code (server & client combined), but I could imagine that, in the long term, the total size could be 200 kLOC or more. We are attempting to use Scrum for development, and we are working towards a CMMI level 2 appraisal.

We are adopting peer review methods to verify our software design and source code. We elicit software requirements during the sprint planning meeting, and we document the software requirements in a master SRS. This also gives us a start into the software design, but we don't have a formal method for reviewing design concepts, such as OO design, UI design, re-usable design patterns, and more. For our source code, we are trying new techniques, such as using spreadsheets to document over-the-shoulder reviews and e-mail pass-around reviews, but it can be difficult for the reviewer to understand the design concepts from just looking at the source code.

(Please excuse me if I am misrepresenting concepts; we are attempting a lot of this from scratch.)

We are not averse to using UML to express classes, objects, software interfaces, event patterns, or other design concepts, but we are not sure when or how to peer review our design efforts. Often, a developer can be 70+% complete with a user story and realize that a fundamental design element needs to be changed (and, subsequently, peer reviewed).

In an attempt to avoid open discussion on the topic and promote concise answers, I'll try to propose two specific questions:

  1. Does anyone know of any good resources (i.e. books, papers, articles) on the best practices of peer reviewing design concepts?
  2. I have read that the code itself is the (implementation of the) design. Can the peer review of source code be utilized as the peer review of design?

Thank you.

Improve this question
7
  • Do you create a Software Design Description (SDD) document to address your requirements specification? You should capture your high level (software architecture) design in a document. MIL-STD-498 is a good starting point (See the SDD PDF linked there).
    – John Lyon
    Commented Aug 5, 2012 at 22:41
  • We do not, but I am open to the idea of implementing one. In the past, each user story would have a design review doc, a code review doc, or both associated with it. When the story was nearing completion, we would gather the entire team and do a formal inspection. However, we feel like this has consumed a lot of time and not effectively conveyed the design or code to the rest of the team. We are moving towards having multiple, smaller code reviews throughout the implementation of the user story.
    – David Kaczynski
    Commented Aug 5, 2012 at 23:53
  • 3
    possible duplicate of How do you deal with design in Scrum?
    – gnat
    Commented Jan 5, 2014 at 12:12
  • 1
    @gnat This question pertains to scrum specifically in the context of CMMI, which requires the documentation of processes to pass appraisal. The potential duplicate does not address documentation or CMMI.
    – David Kaczynski
    Commented Jan 5, 2014 at 15:42
  • 1
    @gnat Good points. Honestly, I wouldn't mind if you went ahead and closed this one. I wasn't 100% sure what to ask when I posted it, and it's been so long, it would be difficult to phrase it in the right context now.
    – David Kaczynski
    Commented Jan 5, 2014 at 17:06

2 Answers 2

Reset to default
1

I think there are 3 things that help good design :

  • Pair programming. This way, you ensure that multiple people know how the design works and how to change it if it is no longer suitable for current requirements.
  • Unit testing. By doing TDD, you can ensure the design is simple enough to understand and subsequently change.
  • Time. In iterative development, the design evolves over time. Noone can tell you if the design is good or bad at the moment it is created. Only after the design changed few times can people tell if the design was easy to understand and change.

P.S. Ask yourself what will code review give to you. Agile is about empowering developers to give them freedom to define your own process. If you don't know what to expect from some kind of process, then there is high possibility you don't need that process.

Improve this answer
8
  • Excellent, thank you. In response to what the code reviews give us, one benefit is the facilitation of metric collection. I.E., we are recording metrics such as the number of defects found per hour of review and the number of defects found per lines of code. Such metrics will allow us to compare the cost of fixing a defect before the code is released versus the cost of fixing a defect after the code is released.
    – David Kaczynski
    Commented Aug 5, 2012 at 17:38
  • What do you mean by "code is released"?
    – Euphoric
    Commented Aug 5, 2012 at 17:53
  • At the end of each (1-month) sprint, the code is packaged and available to the client. That is what I mean by releasing the code. Each month, the client owns a new iteration of the code base.
    – David Kaczynski
    Commented Aug 5, 2012 at 18:55
  • 1
    Do you have a citation for the cost-over-time for fixing bugs in agile being constant? I will provide my citation tomorrow when I get on my work laptop.
    – David Kaczynski
    Commented Aug 5, 2012 at 20:38
  • 1
    Here is the case study I was thinking of, on page 10. I always figured waterfall was the model for how not to do lifecycle management, but the results of the case study do not include hardly any details of the organization.
    – David Kaczynski
    Commented Aug 6, 2012 at 16:36
1

Design is nowadays done solely in UX, they have vast resources on how to do design reviews.

There'll be a lot of people in 10 minutes telling you you're not doing Agile right, forget them: you're doing software right, software is not a religion, Agile is. As long as it creates good software quickly enough, it's fine.

Personally, I'd do data flow diagrams or anything which ensures that all the required information is available at any moment of time in the process. Data flow and its friends (flowcharts enriched with input/output handlings, etc) are a great way to capture missing elements.

Collaborative testing of UML is also easy: one of you prepares by drawing it up on paper first, then gathers the team and starts to draw it up on a whiteboard step-by-step, asking if anything is wrong with his train of thoughts.

In this process, make sure to

  • first, articulate the end-user goal of the given design
  • evaluate all the requirements, perhaps write them on the whiteboard
  • do the drawing
  • denote problematic spots while drawing, bringing emphasis on them.

We had these design sessions nearly every day when I was in a startup comparable on what you have now.

You can also do this on sourcecode, but always remember: a sourcecode is there to explain the problem to a computer. Dependent on language of choice and the problem at hand, the current language might or might not be effective in explaining it to humans as well.

Improve this answer
4
  • Does UX = User Experience? That is a new acronym for me.
    – David Kaczynski
    Commented Aug 5, 2012 at 18:57
  • 1
    Yes, it is.. and IA (Information Architecture) and ID (Interaction Design), whatever... the thing is that creating software is about solving human problems with computers. Therefore, you need psychology and CS to connect the two ends. Programmers didn't want to deal with design, they preferred solely coding instead, and therefore new people came to the scene who actually do the design. They're not as good in technology, and that causes problems a lot of times,but design has to be done. if programmers aren't willing to take it, then the artits will do
    – Aadaam
    Commented Aug 5, 2012 at 19:00
  • -1. From his question and comments. It doesn't seem like he is doing agile right. Also sourcecode should be understandable to both computer and developer. If it can't, then it is bad code.
    – Euphoric
    Commented Aug 5, 2012 at 19:51
  • Ah, an Agilist! :) As I stated, it doesn't matter if you do Agile right as long as your software is cool for its users. Look at Nokia: trust me, they do Agile right, they do TDD, they do everything, still, their software is bad and noone wants to use it, even themselves. And there's a threshold where I integrate / invent a new language in order to have a much clearer representation; that's about 2000 lines. For a single module, I might not change from the team's general language of choice to a different one, or build a translator for it. Sometimes UML is better anyway, as it's 2D and visual.
    – Aadaam
    Commented Aug 5, 2012 at 20:00

Not the answer you're looking for? Browse other questions tagged or ask your own question.