4

I am working in a project in which at many point I need to change the code and fix the bug of the system but how can I inform other team members about this change? Usually I add single line comment to that particular point or create task in eclipse and write bug fix as follows,

//Fixed PRJ110-345 called checkAndClear to clear myObject
myObject = myObject.checkAndClear();

But this does not look good when I change something in properties or sql file of the project.

Moreover I need to search for this PRJ110-345 to find the bug fixed or use regular expression to find all issue number but those might have solved by other team member.

What is the best way to keep track of issues in the code among the team member ?

Sometimes I can not differentiate between my solved bugs and other team member's bug fix. Currently we don't have different accounts for issue tracking system (JIRA) and team leader just distributes the Bugs among team member and it's difficult for me to track my fixes every time.

8

You shouldn't track bug fixes in the code. It might make sense to track some unfixed bugs in the code, as a warning to other developers that look at that code that it has bugs that you didn't get around to fixing it. Something like:

//Currently crashes - see PRJ110-345
myObject.initialize();

But noting in the code that the bug has been fixed is pointless, because the bug is something that shouldn't have been part of the code in the first place - why documenting something that isn't there and shouldn't be there? I can easily introduce new bugs to your code by randomly typing commands into it - for example I can set myObject to null at random places. Are you going to document on every line why myObject isn't set to null on that line?

The place to put these comments is in the source control - and it sounds like you are not using source control, so you should start using one - I suggest Git. A source control (among other things it does) represents the history of your project as commits - each commit is a diff that (together with previous commits) describes how the code looked before the change and how it looks after the change, and allows you to enter a commit message that describes the change - what you did and/or why. This is where you document the bug fix.

So, instead of looking at comments in the code you look at commit messages and see what your teammates did - here is how it looks in on BitBucket. That way, your code stays clean but you still get access to all the info.

5

Giving every line of source code a reference to all the tickets that affected it is not feasible. That's simply too much information, and most of it will be outdated soon after you write it. These kinds of comments are valuable, but they should be commit comments in your version control system, rather than code comments in your source files.

But if I'm reading your post correctly:

I am working in a project in which at many point I need to change the code and fix the bug of the system but how can I inform other team members about this change?

It sounds like your real concern is how to ensure that the rest of your team will know why this line of code is the way it is the next time they read it. In other words, how to make the code readable. There are usually other ways of accomplishing this which do scale better.

If clearing these objects is a normal thing, and everyone on the team is familiar with the concept of checkAndClear(), simply make the code a bit more self-documenting:

checkedObject = uncheckedObject.checkAndClear();

Most of the time, this sort of thing should be enough.

If this is an unusual thing that requires some kind of explanation, then in addition to being self-documenting, leave a comment explaining the real issue:

// Normally we don't need to clear these objects manually, but this one
// comes from Foo.lib which sometimes returns garbage values
checkedObject = uncheckedObject.checkAndClear();

I would only leave an explicit reference to a ticket in the code if we are expecting some future change to the code, and the ticket is about making that change happen:

// TODO: refactor Foo.lib to stop returning garbage values (PRJ1234)

This prevents anyone from opening a duplicate ticket, or duplicating any of the work that's already being done for that ticket, and the bug tracker is more likely to have additional information if anyone has done some work on it.

4

If you try to record the fixes in code, you'll end up with a mess of comments over time that will leave the code unreadable.

As a minimum, you could record the Jira number - PRJ110-345 - in the comment when checking your code in to eg git, or whichever source control solution you are using.

Another option in to use Stash and link that to Jira. That way, your changes show up in Jira.

Arguably the best solution though is to create a new branch for each issue. That way all changes related to PRJ110-345 get stored in a PRJ110-345 branch. When complete, merge back to master. That way you have a complete record of all changes accessible by just examining the history of the branch.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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