Best Practice: Source Code Communication

Java Development News:

Best Practice: Source Code Communication

By Vincent Massol

16 Jul 2004 | TheServerSide.com

The need for source code communication
When you're working in a team one of the most important aspect of development is to know what others are working on, what they are modifying. Indeed, in development everything is tied one way or another:

  • if someone changes the database schema, I need to know
  • if someone updates a build dependency to a newer version of a framework I need to know
  • if someone changes a public API, I need to know
  • if someone starts working on the same set of source files as mine, I need to know
  • if someone modifies a best practice document, I need to know so that I can have a look at what's new

    Basically, I need to know whenever some source file on which my work depend on is modified.

    Of course, I could rely on verbal communications: "Hey Joe, I'm gonna work on this files for the coming 4 hours". Sure, that'll work too. However it's not a scalable solution (Imagine a project divided in 5 teams of 10 persons each) and it works only if the participants are acutely aware of what each developer is depending upon which is near impossible. In addition, if the team is distributed it becomes virtually impossible to communicate such small events in any efficient manner. There has to be a better solution.

    And there is! There are actually 2 solutions I know of, one better than the other.


    Solution 1: Diff emails on SCM commit

    This first solution involves setting up a server-side hook in your SCM. Most SCMs supports executing a script upon source check-in/commit. Just write a script that sends an email containing the diffs between what the user is committing and what already exists in the repository. The reason for the diff is that we're interested by what's different and not by the full content. This is what is done in most open source projects. Here's an example:



    The problems with this solution are:

    • It's not very easy to let the developer choose finely what files/directories they want to monitor
    • The diff information is received in your email, among all you other emails. It's good to reserve emails for actions that you have to perform. Here we're not talking about actions but about information. I believe a better channel for information is for example a RSS feed. It still comes to you but it does not clutter your other emails.

    Solution 2: RSS feeds

    This solution involves setting up some kind of server that will generate RSS feeds for the developers. Implementing this could be quite involved. Fortunately there's a tool called FishEye from Cenqua that does exactly this. It's an improved viewcvs. Most importantly it allows developers to generate RSS feeds on any resource (any directories and any files). Here's what the HTML view


    (Click to see larger image)

    Then here's what you get in your favorite feed reader (I'm using Newz Crawler here):


    (Click to see larger image)

    Clicking on the diff link generates the following view:


    (Click to see larger image)

    Note: Please note that FishEye currently only supports CVS. Other SCMs like Subversion are planned in the future.


    Conclusion

    It is relatively simple and very effective to set up a way to notify developers about changes happening in the repository. I would even suggest that not doing so is a "communication anti-pattern". In order for it to be the most effective possible, developers should not be "spammed" by tons and tons of diff information. Thus to prevent this spamming you should consider 2 options: using RSS feeds instead of emails and allowing developers to choose their feeds. There are obviously some feeds that should be more "mandatory" than others. For example, the one notifiying of database schema change, the one notifying of build changes and the one notifying of public API changes. It's important, as always, that there is a champion in the team, explaining to others the benefit of these feeds and how they should be best used. Otherwise the power of them may exist but it won't be harnessed.



    About the author

    Vincent Massol vmassol@pivolis.com Blog: http://blogs.codehaus.org/people/vmassol/
  • Related Resources