Commenting approach: How to comment something that's used elsewhere in app?

My IVR app contains a lot of global variables, as a side effect of an inescapable vendor-supplied framework. As such, there are a lot of cases where a variable is given a value on one JSP, and is not touched again until a cal开发者_如何转开发ler has gone several dialogs deep into the app.

When I have to add or modify such a variable, I leave a preamble comment that describes the modification, without going into detail on the whole piece of functionality:

<%--IVRAvenger 20100927 Issue#:12345: Keep track of what the caller entered.  Used for multiple ID/ID change logic, further on. --%>
<assign name="gblIDInput" expr="memberID"/>

Is this misleading? Would it be better to simply add these small statements, and let other developers scan the code for the module where these variables work their (questionable) magic?

Thanks,

IVR Avenger

With a problem such as this, I would recommend an external dictionary document that lists the global variables, the purpose and typical work flows associated with them.

You may also want to list the major modules that use the variables. While this data will get out of date, it will provide a starting point for somebody having difficulty maintaining your application.

If you do implement such a document, I would also recommend any overall patterns or philosophies that are embodied by the code. Including known bad choices and why they were bad choices wouldn't hurt. Since most developers won't read (and of course maintain) such a document, you are either writing for the new hire that was given documentation as a task or a future maintainer that has finally gotten frustrated enough to actually read the documentation.