Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
6  
svn may help, as they will come to know they something has changed in the code..so they can directly update your changes (specific file may be in your case)..without having to know what has changed (optionally if they dont want to) –  cod3r Feb 8 '12 at 4:44
    
it's a class you've written not an object :) objects exist at runtime not compile time –  Rune FS Feb 8 '12 at 11:12

5 Answers 5

up vote 9 down vote accepted

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).

share|improve this answer
2  
+1 I think everyone on the team needs to be educated to not "blindly" update to the latest version of the code but briefly check what has been done and where before doing it. And as you said, a short but precise comment is great. –  Jalayn Feb 8 '12 at 9:24

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.

share|improve this answer
    
+1, somehow the most obvious answer is not thought of first! –  Emmad Kareem Feb 8 '12 at 14:04

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.

share|improve this answer
6  
This sounds good in principle, however: 1. a design document that contains every single class attribute is going to become a pain in the ass to maintain and keep in sync with the code. 2. a UML diagram reverse engineered from code is bound to become practically useless in any nontrivial project pretty soon, again due to the sheer amount of details in it. –  Péter Török Feb 8 '12 at 8:02
    
You dont need to document every single class if you have too many. Just the ones that make up the public interface. Agree that for a large project it will become cumbersome, but it is better than not having any document that specifies how the various parts of the application talk to each other. –  DPD Feb 9 '12 at 6:23
    
I agree about the importance of a high level architecture / design document (as noted in my answer). However, that is high level precisely so that it doesn't need to be constantly updated with minuscule changes. –  Péter Török Feb 9 '12 at 8:19

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.

share|improve this answer
    
Maybe I have never worked with good teammates, as I have never seen this work in practice :-( –  Péter Török Feb 8 '12 at 8:39
    
@PéterTörök I have to admit that they are far and few in-between, myself included. –  tehnyit Feb 8 '12 at 12:38

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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