Month: May 2009

What is Success?

The more time spent on words, the harder it gets to define. Yesterday I had a talk to a friend, about the problem in consultancy for measuring “success”.  It gets complicated, are we talking about “a result comparison of the planned time and budget to the actual data” or “a comparison to what it should have achieved.”

If compared the actual time and cost to the planned one, sometimes not delivering a project has more benefits; it can be a good learning experience [not preferable one but since there is a phrase: success comes from experience and experience comes from failure]. Even cancellation can provide more advantage; a good risk analysis at the very beginning of the project can save many resources beforehand.
If compared to what it should have done something better, then the question “what were the alternatives and how could it have been achieved” raises.  The expectation/understanding from success changes the further we go.

Then, confusion starts with “decision” word. “How would it be done in a better way”, “what were the expected results”? [I won’t continue now, but I am sure you get the idea]
Even if I start to make assumptions and select a path to reach a final understanding of a word success, it will be unique to my understanding/imagination/knowledge and experience. While you are reading, I am sure you have come up with lots of more questions for each confusion.

“Being aware of what you want” is challenging enough, and I won’t go further with asking “being sure about what you want.” Do you really want it? Have you done enough analysis? Are you confident enough? [Is confidence a good thing?]  I don’t know.

As the scope gets bigger, the answer gets more unconclusive. I reckon, that’s where agile methodologies help us to have smaller, achieavable, forecastable projects.  Being aware of the big picture, but relying on what you have in the smallest piece on your hands.

Development Models

To minimize the risk, to deliver a successful project, teams look for a methodology that they can rely on. Most of the development methodologies started with the idea of manufacturing systems: “X delivers high quality, efficient and excellent products applying Y methodology, why we can’t?”
X is one of Japanese companies, and Y is applied on assembly line. But since, we can convert a developer into a computer, we can apply the same logic, can’t we?
Both have project plans, design and production phases. Both have quality assurance, and apply TQM principles.
They should have budget, risk analysis and decision phases…
However, software projects have unique products per projects, where manufacturing companies are producing same lego pieces. Once they have a specification, all lego pieces can interact with each other, and can produce millions of them…Once you have a specification for a part, you produce it, and that’s all, reusable code can be consumed for the new project, but probably they will pick a new language/technology and will not use it, since production of a piece takes three months up to three years… 
I can’t make generalizations because there are trillions of parameters around this subject.  But I had a training on a new methodology last week. [It was an iterative and incremental methodology developed for company].
To be able to outsource, that put planning, analysis and design phases into iterative cycles, and finished the iteration with implementation. The model/documentation that will be handed to outsources can’t set into stone. To make risk analysis perfectly, you can’t assume during development any risks will not arise, and the analysis should not be reviewed.  Throughout all my development experience, I did not have any project changing requirements, changing scope/analysis after all planning phases finishes. But then, it was upto developers to ask questions and contribute to the depth/quality of the delivery.  If you are going to outsource, and trying to perfect your documentation, i.e. every piece of code developers are going to write is in [uml] documents, you can’t expect outsourced developers not to ask questions and change your analysis documents.
Waterfall was not useful, since it was set into stone assuming all phases will be done one by one without review/update.
Iterative and incremental process was not useful, since it was helping with the outputs/artifacts.
However, I am not happy with this model as well since it is a spiral model without any implementation cycle.

Documenting the code

If a new framework is developed in your company, and you are going to use it, without proper documentation you can face lots of difficulties. It may company culture “to go and ask questions” but it can be a pain after five questions [ten maybe?]

With defensive programming, and agile methodologies around, lots of developers write their unit tests, created their exceptions carefully, every piece of code is in UML diagrams [object and sequence models,…] but unless it is a culture, nobody creates comments in their code.

Some does, but this becomes more confusing since there is no standard, a few people apply their own standards…

From the very beginning of the .NET [and C#], <summary> tags are there for documentation…This time, I will give  some examples how to use it. 

namespace  EC.Domain.ProductDMgr{ 
/// <summary>  
/// Product Data Transfer Object  
/// </summary> 
public class ProductDTO{ 

  private readonly int prodId; 
  private readonly string title;  private readonly int dissection; 
  /// <summary> 
   /// ProdId is the product Identifier 
  /// </summary> 
  public int ProdId { get { return prodId; } } 
  /// <summary>Title is the title of the product</summary> 
  public string Title { get { return title; } } 
  /// <summary> Dissection is the department of the product </summary>  
  public int Dissection { get { return dissection; } } 
  /// <summary>   
  /// The constructor of the product with identifier and title 
  /// </summary> 
  /// <param name=”prodId”>Identifier of the product</param> 
  /// <param name=”title”>Title of the product</param> 
  /// <param name=”dissection”>Dissection of the product in the store</param> 
  /// <exception cref=”ArgumentOutOfRangeException”> Exception for Dissection bigger than 999</exception>  
  public ProductDTO(int prodId, string title, int dissection) 
  this.prodId = prodId; 
  this.title = title; 
    if (dissection > 999)
        throw new ArgumentOutOfRangeException(“dissection”, “Dissection should be equal or less than 999”); 
    else
    { 
         this.dissection = dissection;
     } 
  } 
}
Anyone  using your assembly should be more confident about the objects and parameters now:

 

Object_Browser

And during the development, that will add extra mile speed to the project:

Yellow_Window

For detailed info, you may refer to msdn.

There are codeplex projects [SandCastle, AjaxDoc] running on to extend this documentation and create msdn like help documents/websites.

Cleaning the Code

As UncleBob discuss on his article Commented out code is an abomination, leaving codes commented out does not help the other developers to understand/write the code better, but only create problems. I will keep the same example he gives, for clarity and assuming everyone saw at least one piece of code similar [no, no I know you did not do]. Here is the example he gives:

protected void log(String message, int priority) {
      if (project != null) {
        project.log(message, priority);
      }
//      else {
//        System.out.println(msg);
//      }
    }

First of all, it breaks the rule of xp, “don’t code for future.”  Probably the developer was thinking writing to console will be a requirement in future, and wanted to help other developers going to use his code.
The code should be as simple as required, just doing what it should do. Adding extra complexity will create lots of questions.

Secondly, if he really wanted to leave a comment, it should not be a commented line, but a comment to the top of this functionality, telling what it is in his mind : “This if may have else statement writing the code to the console.”

Thirdly, and worst case: breaking another rule for defensive coding: he could left it for himself….
It was a requirement, but he couldn’t write/compile it as he wanted. Maybe he wanted to write a xml file, but could not [did not have time…], and left this commented part as a reminder [believing without comment he will remember…].
And maybe because it was not mandatory, he delivered without an else…
Obviusly, he may want to add optional else part with a functional code later [if he can]…
Then, I reckon, he should add TODO: keyword to the start of his comment:  
“TODO: This if should have an else statement writing the message to xml file”
Lastly, it was an important piece of code [lots of lines…], and he wanted to keep it to use later since he was not confident to write the same again himself. I could offer to have that piece of code locally and  write a reference as a comment.
Then he can argue that “I want it in source control so that I won’t lose it!”
I would not mind creating a commented lines file, and extract this piece of commented lines as a method and referencing the method name here.

All in all, I can’t see a point in commented lines to stay there…
It should not be the new developer looking at code, and deleting old codes [requires some courage since she may lack some knowledge] , but the owner of the code should really be responsible for his code…

C# is quite handy in terms of writing comments and creating documents from code. In the next blog, I will show some nice examples. Writing solid codes should not be that far away…