Collaborative Debates

Today at work, our boss decided to have the developers play out a mock debate in order to bring about a requirements discussion. I suppose it was intended to be a fun, quirky, roundabout way to get the whole team involved in requirements analysis, since it's been a common pain point for our current project. I would contend that the pain point is in having requirements delivered to us rather than properly discussed in our team, but that is beside the point.

We divided into teams and each took a side in a debate regarding whether to use an open source framework's ACL system or one we had recently developed in-house. The in-house system was developed because our framework's version didn't fully meet what we believed to be the requirements imposed on us. In the end, each side was challenged to present a case for their side, irrespective of their opinion on the matter. Some fuss was had, but the exercise commenced, and our cases presented.

In the end, the event devolved into a back-and-forth session with our CEO (small company) regarding the company's actual needs concerning what was before considered a minute detail of a far more massive project.

My takeaway was that while a lot of time was wasted, I think it illuminated the fact that it's quite easy to make assumptions about seemingly trivial details that are completely wrong, and by now we've wasted quite a bit of time learning that lesson.

Unfortunately, we're slated to do the same with our DAL/ORM layer, arguing two solutions which are nearly identical save some syntactical sugar. I fail to see what good can come of that, but I can hope, for now.

Comments

When you comment your code, what, exactly, are you documenting? It's a question that I think a lot of developers should ask themselves. What kind of information would be valuable for CluelessNewbie_01 as he peruses your code?

My approach, though I don't always adhere to this, has lately been to explain why the code is doing something, rather than what. I feel that if I feel the need to explain what, then I should probably start renaming symbols and refactor in order to make the code easier to understand.

Take for example the following PHP code:

protected function formatHumanReadableXML(DOMElement $delRoot = null){
  if (!isset($delRoot)){
      $delRoot = $this->ddcOwner->documentElement;
      // Remove the whitespace
      $this->removeWhitespace();
  }
  // Copy the children into an array
  $arChildren = array();
  foreach($delRoot->childNodes as $dndChild)
      $arChildren[] = $dndChild;
  .
  .
  .
  .
}

Now, were those comments very helpful? No? You could tell what was going on by just reading the code, couldn't you? I've changed the code to be more helpful in the comments:

protected function formatHumanReadableXML(DOMElement $delRoot = null){
  if (!isset($delRoot)){
      $delRoot = $this->ddcOwner->documentElement;
      /* Remove the whitespace, because this brings the document
             to a common starting point, containing no whitespace, so
              we can add tabs and breaks at our leisure*/
      $this->removeWhitespace();
  }
  /* Copy the children into an array before looping over them, since
   we may be appending children to this element (thereby changing
  the childNodes list) */
  $arChildren = array();
  foreach($delRoot->childNodes as $dndChild)
      $arChildren[] = $dndChild;
  .
  .
  .
  .
}

Now can you see what the point of that code is? A world of difference, I think.