Planned change comments tracker

I was thinking of a possible extension to the TODO concept. But, before I submitted a tracker request for it, I wanted to see what others thought.

I sort of did a little wishful thinking with it; aim high and hope for the best. :)

Basically, this is sort of a mini change control, planned changed, or work in progress concept.

Have you ever gone into code to make a change that you thought was small, but then as you looked into it more, it sort of grew. For example, as you are looking at it, you realize that there are places where you should apply some refactoring(moving methods to different classes, getting rid of bad code, and such).

Or, you started on a change that you new was going to be large and spent time going through the code to figure out where you were going to make the changes?

Anyway, I thought it would be handy if there was some way that we could use IDEA help us document and track where we needed to make code changes.

Now, I am not talking about anything too elaborate( I hope), just something to help us along. Something to help us organize, track, and move around in our projects for a specific planned change.

Also, I think this idea could be used to handle some TODOs, in that instead of just sticking another TODO in a class, you might be able to link it with something more specific, for future review.

Now, to how it works; conceptually speaking, that is:

First, if you were going to make a planned change, you would register the change in the project through IDEA. This registration would be something fairly simple, like giving the change some type of short identifier and short description.

For example(100% completely conceptual):
ID = userprops
Description: Expand user property tracker to handle dynamic property names, along with the fixed names.

There, now it is registered in IDEA for the project I am working on.

Now, as I go through the code, where ever I planned to make a change, I would add comments such as:

//PC:userprops:10:Add Properties
//PC:userprops:20:Add accessors
//PC:userprops:30:Add move this method to UserProfile class

For this example, the colon(:) is used as a positional separator.

The //PC would be the identifier for Planned Changed.
The first positional item would be the change ID; in this case userprops.
The second positional item is simply a sequence number, so that it might be possible to sort the sequence of what you are doing; you could optionally leave it blank.
The third positional item is a short description of what you are planning on doing. If additional documentation is need, you would just add additional comment lines after the PC line.

Now, IDEA could help us with adding of the //PC lines in two ways. First, there would be a setting for a planned changes in progress setting. That is, you would tell it which planned change ID to insert after the //PC:. Of course, if need, you could insert a different ID if needed.

Second, it could track the highest sequence number used and increment it for you by a user defined amount.

You would just insert the comment.

Later, when you planned to execute the planned change, you would tell IDEA which planned change you want to work on and track; Work In Progress.

This would tell IDEA which planned changes to track and highlight for you. Sort of like a TODO filter, but with out the need of setting up all of the filters.

You could also use this to bring up a list off all of the planned changes, or a list of all of the classes that have one or more planned changes in them.

Or, you could just bring up a list of the classes for a specific planned change. This could help you in your final planning and review, and in your debugging, since you could use this list to easily jump to the places where you made planned code changes. And, if you made some unplanned ones, you could still insert a //PC: in to the code for tracking; such as a //PC:userprops:9999:Altered load routine.

After your changes have been made, tested, and moved to production, IDEA could go and delete the //PC: lines for the planned change.

So, in short, here is what I think would be needed:

A simple project level change tracker. At the minimum, it would track some user defined ID and a short description. For a little more flexibility and usability, there would be room for a longer or more detailed description, some type of status(planned, active, on hold, halted, completed, aborted), and/or maybe a few dates(Created Date, Started Date, etc.).

We will need some way to indicate which planned change(s) we are working on at that time. Like with TODOs, we would get the little indicators(will have to come up with some color, maybe green), so that we can easily navigate in our code to the specified //PC: for the currently active planned change. That is, if there are //PC: for other planned changes, those would not be noted/highlighted.

A variation or expansion of the TODO list that allows you to view all Planned Changes, a specific(or active) planned change and the steps involved, classes affected by planned changes, or classes affected by a specific(or active) planned.

Some automation in adding the //PC: comments to the code. The automation would be in the area filling in some of the parameters for the //PC: and a way of changing them; most specifically a popup listing all of the available planned changes and, possibly, a popup showing all of the steps that have been added for a specific planned change(so that you can pick the appropriate step number).

A quick clean up process. This would just remove the //PC: lines for a specific planned change. Any additional comment lines would have to be handled by the user, if needed.

Of course, a possible expansion of this concept is to allow for more than one planned change to be active at any one time. That is, if I have two planned changes that are closely related, I could make both active at the same time.

Anyway, there you have it. Any thoughts, comments, suggestions, or obscenities? :)

1 comment
Comment actions Permalink


>So, in short, here is what I think would be needed:
>A simple project level change tracker.

Your request is pretty complex, but the summary is way simpler.

So, it makes me wonder if this feature :
Wiki like active links in text file to the java code

wouldn't serve you well enough, in a much much simpler way.

If you think so, it's still to be discussed, and you could add your use
case to the thread.



Please sign in to leave a comment.