uima-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Richard Eckart de Castilho (Jira)" <...@uima.apache.org>
Subject [jira] [Comment Edited] (UIMA-6248) Code comment with issue number
Date Wed, 24 Jun 2020 08:39:00 GMT

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

Richard Eckart de Castilho edited comment on UIMA-6248 at 6/24/20, 8:38 AM:
----------------------------------------------------------------------------

The idea of your tool is helpful, but the implementation cluttering the source code with comments
- and that in my personal opinion is not helpful. In a few cases, I may care to add an issue
number manually to a comment - but usually I do not. If I want to see the issue numbers, I
use the annotate/blame functionality of the version control tool and pick them up from the
commit messages that way. Having all these comments directly in the code is simply too much
for my taste.

 !Screenshot 2020-06-24 at 10.36.32.png|width=100%! 

In the screenshot above, you can see the blame/annotate functionality in action in Eclipse.
Superimposing the information on the code when I need it is IMHO much more convenient than
permanently having the comments in the code.


was (Author: rec):
The idea of your tool is helpful, but the implementation cluttering the source code with comments
- and that in my personal opinion is not helpful. In a few cases, I may care to add an issue
number manually to a comment - but usually I do not. If I want to see the issue numbers, I
use the annotate/blame functionality of the version control tool and pick them up from the
commit messages that way. Having all these comments directly in the code is simply too much
for my taste.

 !Screenshot 2020-06-24 at 10.36.32.png! 

In the screenshot above, you can see the blame/annotate functionality in action in Eclipse.
Superimposing the information on the code when I need it is IMHO much more convenient than
permanently having the comments in 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
>         Attachments: Screenshot 2020-06-24 at 10.36.32.png
>
>
> 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/uima-uimaj] 
>  
> 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)

Mime
View raw message