How to let teammates know what changes I made to an object? [closed]

Question

Suppose I have a PHP object, let's say: companyObj.

class companyObj
{
  private company_name;
  private company_address;

  public function print_contact()
  {
    //logic
  }
}

This is the object I wrote, and shared with the teammates. Now I would like to make it more powerful, like this:

class companyObj
{
  private company_name;
  private company_address;
  private company_contact_person;

  public function print_contact()
  {
    //logic updated
  }
}

Now, how can I notify my teammates that my object had more attributes that they can set?

Instead of sending e-mail to everyone in the development team, how do I make the team know what's going on, when I don't want my teammates to waste their time to look at what is changed at the source code level?

Answer 1

It depends a lot on the concrete situation. Let's assume the new property you added is mandatory, i.e. it has to be set always. Then you must search through the code yourself and update it everywhere a companyObj is created, to ensure that it is constructed properly (including setting the new property). I assume PHP has constructors, in which case you only need to add a new constructor parameter and the compiler will automatically mark every constructor call without the extra parameter as a compilation error. This will also ensure that teammates learn about the new property as soon as they use a companyObj.

If the new property is optional, however, things are less clear. You may or may not have a suitable default value for it. In the latter case, I would still suggest you update all instance creations to set the new property whenever appropriate. This is to ensure that the code is kept in a consistent state at all times.

Communicating the change to your teammates is another, distant step here. Agile teams prefer face to face communication, and, IMHO for a good reason. Relying on documents is a very slow and ineffective means of spreading information around a team. A Wiki is somewhat better, but still, documenting every single class attribute is IMHO overkill. It is only going to become a huge burden on the team, and is quickly bound to become unreliable and useless anyway, as we are humans so we are bound to forget the update sometimes, moreover I bet that not many team members are going to regularly check the documentation (be it in whatever form) to get informed of the latest code changes.

The latter is also true to automatically generated documentation via e.g. Javadoc or Doxygen. Although they can be configured into an automatic build to keep the generated documentation up to date at all times, I have never seen a development team with members regularly browsing through the documentation to get informed about the latest code changes. And if you are using any source control system, the first place to notice the changes is when you update your local copy of the code anyway - then you can check for changes in familiar classes and see precisely what and how has changed (along with a brief explanation and/or reference to a task ID, if your team is accustomed to add meaningful checkin comments - which is going to be missing from automatically generated docs).

Communication is one prime reason why Extreme Programing teams do pair programming. If you make the changes together with a teammate, there are two of you right away who know about each change, and next time each of you are going to pair up with someone else, so useful information spreads quite quickly. It is not always applicable though, for various reasons. Barring that, you may simply talk to your neighbours about the change in an appropriate moment (e.g. during lunch, if you happen to lunch together), or send a mail around if it is a bigger, more important or more complicated change.

In the latter case, there may be a good reason to document it properly. IMHO design documents are best when they offer a coarse grained, high level overview of the system, while the implementation details are in the code (adhering to the DRY principle).

Answer 2

Have you considered simply talking to them? Schedule a short meeting: "hey, I made some changes to object X, I want to show you what changed and why". Or, just talk to each person individually if a meeting seems too formal or disruptive.

Answer 3

If you have a team you probably also have a design document. If not. get started on it. And use some UML tool to map your designs.

Answer 4

You could use a tool like doxygen within you code. Now create script that would generate the doxygen documentation and run it regularly, perhaps as part of your nightly build (you do a nightly build, right?).

I think you can assigned a custom attribute in doxygen to your addition to highlight it as being new.

If your teammates are any good, they would go through the new documentation.

Answer 5

Now, how can I notify my teammates that my object had more attributes that they can set?

Well, you shouldn't inform your teammates about every little thing you make. Otherwise, you'd have to send lots of emails. If it is a big thing, then you can make a small meeting, and let them know what you did (If you do scrum, then no need to set a separate meeting).

If you use an IDE that supports auto completion, then your teammates should notice your change. I just hope you do comment your code.