[jira] [Commented] (UIMA-6248) Code comment with issue number

["Richard Eckart de Castilho (Jira)" <de...@uima.apache.org>]

    [ https://issues.apache.org/jira/browse/UIMA-6248?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17142739#comment-17142739 ] 

Richard Eckart de Castilho commented on UIMA-6248:
--------------------------------------------------

From your commit/fork, it looks like you add a comment for every block of code which was changed in the context of a particular issue.

I personally would find it very annoying to have all these comments in the code. I see the utility of course and I even have a specific project where I quite meticulously mark every change I make in the code with a  comment linking it to an issue - but this is case is very special because I want to be able to see which changes are mine and why I made them and which code is still the original upstream version of the code I forked.

Within Eclipse, I often use the annotate/blame functionality of git to see the history of a particular line of code along with the commit comments. Currently, I often click back through different revisions manually. Having a nicer summary of the changes to a particular line or set of lines in Eclipse would be nice - or the ability to auto-detect issue numbers in the commit messages so I could just click them to open in the browser (not sure if Mylyn can do that already in Eclipse). So I would personally prefer this as an IDE functionality and not as something to be rendered as comments directly into the code.

> Code comment with issue number
> ------------------------------
>
>                 Key: UIMA-6248
>                 URL: https://issues.apache.org/jira/browse/UIMA-6248
>             Project: UIMA
>          Issue Type: Improvement
>            Reporter: ackelcn
>            Priority: Major
>
> When I read the code of uimaj, I find some comments with issue numbers. One of them comes from OperationalProperties_impl.java:
> {code:java}
>     // overridden to set proper defaults
>     // https://issues.apache.org/jira/browse/UIMA-2350
>     // These change depending on the element which is the parent of the parent of this element
>     String grandParentName = "";
>     Node p = aElement.getParentNode();
>     if (p instanceof Element) {
>       Node gp = p.getParentNode();
>       if (gp instanceof Element) {
>         grandParentName = ((Element) gp).getTagName();
>       }
>     }
>     setModifiesCas(grandParentName.equals("casConsumerDescription") ? false : true);{code}
> These comments are quite useful for other programmers and me to understand the code, but I notice that not all issue numbers are written in code comments. It can be already quite tedious to write them into commit messages :)
>  
> To handle the problem, I implemented a tool to automatically instrument issue numbers into code comments. I tried my tool on activemq, and the instrumented version is [https://github.com/ackelcn/uimawithissuecomment] 
>  
> To avoid confusion, if there is already an issue number in code comments, my tool ignored the issue number. All my generated comments start from //IC, so it is easy to find them.
>  
> Would you please some feedbacks to my tool? Please feel free to merge my generated comments in your code, if you feel that some are useful.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)