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

My IVR application contains many global variables, which are included as a side-effect of an indispensable vendor-supply framework. Are there. As such, in many cases where a variable is given a value on a JSP, it is not touched unless there is a lot of dialog in the collar app that does not go deeper.

When I have to add or modify such a variable, I leave an introductory comment that describes the amendment, without expanding on the whole piece of work:

  & lt;% - IVRAvenger 20100927 Problem #: 12345: Keep track of what the caller has entered. Multiple ID / ID changes are used for logic, and further. -% & gt; & Lt; Assign name = "gblIDInput" expr = "memberID" />  

Is this confusing? Would it be better to just add these small statements and other developers should scan the code of this module, where this variable works as their (suspicious) magic?

Thanks,
IVR Avenger

One such problem With, I would recommend an external dictionary document that lists the global variables, the purpose and the specific work flow associated with them.

You can also list the main modules using the variable. While this data will be outdated, it will provide a starting point for anyone who has difficulty maintaining your application.

If you apply such a document, then I recommend any overall pattern or principles that are written by code. Known bad alternatives and why they were bad options would not hurt because most developers would not read such a document (and will definitely keep it), then you are writing for new merchandise that keep the document a work or future. - was given in the form of maintenance, which has actually become frustrated enough to read the documents.