- Which changed lines of code belong to a specific ticket in the issue tracker? Example: after deploying the version of our application including feature #42 the application crashes often with a memory leak. We need to review all changed lines of code for e.g. unexpected side effects.
- Why has a specific piece of code been implemented in the way it is? Example: the business expert believes that there is an error in the computation of discount rates for our customers. We need to read the corresponding code, understand the computation of discounts and explain it to the business expert. After that the expert states that this is a bug we are responsible for. Now we have to proof that the implemented behavior has been specified by showing when and were (e.g. a specification document).
All in both examples we need a mapping between code and spec-documents (e.g. issues in the issue tracker like Atlassian JIRA):
- We know the issue and need the changed lines of code.
- We know the changed lines of code and need the issue.
How could this relation be realized in the code? A simple approach could be to mention the issue id in the commit comments of the version control, e.g. "Fix issue #42: fix memory leak by clearing the cache regularly". With this approach were are able to identify all changed files for a given issue as well as the issue for a changed file.
But in case of modified existing code this approach might be too crude. We need the issue more granular per lines. It would be possible to extract this information from the file's version-history of the version control. But this could be very time consuming. This is why I started in my current project to mark changed lines with an inline comment:
// Changes due to issue #42
…
doSomeStuff();
…
// End changes due to issue #42
This has the big advantage to identify changed lines per issue with a simple full text search. But there is also a big disadvantage: after some changes the readability of the code decreases due to the marker-comments:
// Changes due to issue #42
…
doSomeStuff();
…
// Changes due to issue #07
…
doSomeMoreStuff();
…
// End changes due to issue #42, #07
Yet I do not know a sophisticating solution to this disadvantage and would be pleased about comments by the readers of blog :). Feel free to post your experiences and opinions.
There is no solution to this, except for some kind of META-information that is kept along with the code, on a per-codeline-basis. This is what it boils down to - documenting each line. If it was on a method-level basis some smart architect could surely come up with something like Annotation-based documentation but in regard to what you mentioned I don't see any other possibility.
AntwortenLöschenHi Rias,
AntwortenLöschenI think your term META-information is really interesting because it made me think of a special kind of code editor. If the META-information has a standardized format, the editor could parse and hide it. For example one could imagine such an editor as part of the Eclipse IDE. This editor wouldn't show the META-information as text in the code window, but displays a small Icon next to the current code line number on the left. After moving the mouse on this icon, a tool tip could show the issue ids which led to this line of code.
So long,
Jan Christian
hi jan,
AntwortenLöschenif you work with eclipse 3.6 or 3.7 (and not with an old wsad :-) , you can use the feature "show annotations" to see who has changed what, the revision and also the comment.
but this also show you "only" the actual class.
for more information you must look into your cvs/svn/...
in my opinion this is the right place for your comments. if you connect your jira with your archive-system, it is possible to open the issue which was the trigger for the codechange.
if you use comments to mark the issue in the source code after a while you have more commets than source code.
german saying: "vor lauter bäumen den wald nicht sehen" ;-)
cu jocki