So like probably many people out there I usually comment out code temporarily, mostly for debugging purposes. I currently put something like **DEBUG** or whatever that is easily searched for, but I thought having the compiler output a warning (or even an error) whenever it finds code that is temporarily commented out could be useful. I thought of using an annotation, but annotations can't be used to mark comments.
Does anyone know of a better approach than putting an easily searchable string in the commented-out section of code?
there are plenty of code inspection tools out there that can alert you to the presence of code patterns that you define. most of them have built-in support for detecting common stuff like "//todo" comments left in code etc.
most IDEs support auto-detection of //todo as well (intellij idea, for example).
a common command-line tool for this is checkstyle. you could run it as part of your build and have it point these things out to you
At least Eclipse allows you to use (and define your own) markers put in comments, that can be easily listed afterwards. There's at least TODO and XXX, but I believe you could make your own as well.
If you're using Maven, consider to use the taglist-maven-plugin.
Related
Environment: IntelliJ IDEA Ultimate 2022.2 Build 222.3345.118
I have overridden the method with #Deprecated annotation.
I want to suppress deprecated API usage on certain methods. But the Option+Enter action has only useless suggestions.
We tried to suppress it by means of SupressWornings and //noinspection ScalaDeprecation. I would like to disable Inspection as a last resort because there are some warnings that I want to suppress and others that I do not want to.
In Scala you can use the #nowarn annotation to this end. You can see a very nice rundown of how to use both this annotation locally or other options on the overall project on this blog post by Lukas Rytz.
In your case, I believe you can use the following annotation:
#nowarn("cat=deprecation&origin=your\.package\.YourDeprecatedClass")
You can see an example of how I used this on this commit.
As you can see, the annotation can be applied even to individual expression via type ascription, but you can also apply it to methods. In general, I like to keep my #nowarns as specific and fine-scoped as possible. You can also tell the compiler to warn you when a #nowarn is not doing anything, so that you don't have to keep unused annotations around the code.
If you have deprecated APIs that you need to use (e.g. even though they are deprecated, you still need to test them) and the usages are all over the place, you might want to evaluate the option of configuring the warning suppression as a compiler option with something like
-Wconf:cat=deprecation&origin=your\.package\.YourDeprecatedClass
passed to the compiler. Here is an example of this as well (we use Bazel instead of SBT but I'm fairly sure that setting up SBT for this is quite simple).
For any other information, the blog post I linked above is an excellent source.
I want to do something like this:
#Testing
private void methodThatGivesWarningIfUserTriesToUseThis() {
}
where #Testing is a custom annotation/decorator in Java. I'd like the behaviour of this #Testing annotation to act ALMOST EXACTLY like the #Deprecated annotation - if i or someone else accidentally tries to use this in other parts of the code, the IDE will give a warning (and the method name also has a strike-through across the font). So for ex
how do i do this?
**note: i do not want to use #Deprecated because the method is not deprecated, i just want only to use it for testing purposes
**this marker should also be checked at compile time, not runTime.
The problem is that annotations are, as their name states, only for annotating :)
Creating such annotation is pretty easy, you need to do something like this:
public #interface Testing
In order for it to be used by your IDE at compile time you have to write a plug-in.
Here is a good start I found in another SO question for starting with the plugin development.
It sounds like you're describing something like #VisibleForTesting, which is part of the Guava libraries (formerly known as "Google Collections"). If you do create one of your own, you'll probably want it to be #Documented and #Retention(SOURCE).
I'm not aware of any hook or feature that would cause non-#Deprecated members to trigger warnings or IDE flags as if they were #Deprecated. Because the Mirror API and Reflection API don't track individual expressions and statements (as documented in this SO answer), you probably won't have much luck detecting it yourself without a full Java parser.
You might consider writing a custom Lint rule to solve this problem. When your #Testing annotation is detected, the IDE would show a Lint warning (e.g., a yellow underline in the case of Eclipse+ADT).
A detailed guide to scanning Java source files for specific issues with Lint can be found in the Android Tools docs here.
Hi guys: Is there an open source way to associate java #annotations to functional requirements, or for example, TRAC tickets, etc? I want to do something like this:
I'm thinking along the lines of an eclipse plugin which somehow links up with another FOSS project tracking tool, wiki, or maybe even a CSV file.
A somewhat silly but exemplary illustration of what I desire is below:
#Requirement WalkDogTwiceADay
public void walkTheDog()
{
}
#Requirement WalkDogTwiceADay
public void dogWalkerThread()
{
walkTheDog(); //in the morning.
Thread.sleep(36000000);
walkTheDog(); //at night
}
Annotations are metadata, they simply add information to your code for other tools to use or to be inspected at runtime via reflection.
One thing you can do is write an annotation processor that will generate the necessary artefacts. Those could be configuration files, scripts, code...
Another thing you can do is write some tool that knows how to interpret your annotations and uses reflection to find them and take the appropriate actions. For this you'd need to make sure that the annotation type is set to have runtime retention, as opposed to only source or class.
Perhaps some of the stuff found in the answers to this question might prove of use. If that's the case, go ahead and use it. But writing custom annotation processors or code for handling them is not all that terribly hard. The difficult part is getting to know the Java model API that's used by annotation processors, which is like reflection but at compile time (before you have fully-formed classes).
in a previous life, we did something similar with #requirement ##### annotations, and then had a custom javadoc task that turned the requirement annotations into hyperlinks in the javadocs.
I was going to write an addin for eclipse that turned them into links in the code as well, but never got that far.
I am working on a java project and I have to extend (add more functionality) it. But I don't know how should I learn the existing one before incorporating them.
Is there any specific path I should follow?
Can I run it in a way so that I can see, statement by statement, the execution of the program?
I am a kind of stuck in understanding it, thanks.
Here is another approach that is hacky, but I've found useful in the past when unable to attach a debugger. If there is a piece of code that you are looking at, but are having a hard time figuring out who is calling it you can throw a new runtime exception, catch it and print the stack trace.
try {
throw new RuntimeException("who is calling me");
} catch (RuntimeException e) {
e.printStackTrace();
}
You can always fire it up in a debugger/your IDE of choice and step through it all you want, though it's probably best to find someone who is more familiar with the source to provide you an overview, or to look for documentation on where to start.
Pick one piece of functionality for which you understand the requirements. Find the entry point for that feature and follow the code for that one feature. It should give you a good understanding of how the architecture works.
Integrating with code that is already written can be very difficult. In my experience, some of the best clues I've gotten about already-written code come from the method signatures (the mapping of the function's input to its output). The method's signature can give you a lot of hints about a program, namely where and especially how that particular method fits in the context of the larger program. Usually, a method signature coupled with a descriptive method name can give you enough information to be dangerous, especially in a typed language like Java.
Although I wouldn't suggest running the code line by line and looking at changes (because this usually amounts to tons of work) but for really ugly but important code sometimes it is necessary (I've definitley done it before using DDD for C programs). In this case, a quick google search reveals http://www.debugtools.com/ , a graphical java debugger, which may do the trick; there also seems to be version of DDD that works with Java.
This is a recurrent question on Stack Overflow. There is already very good answers all around:
https://stackoverflow.com/questions/3147059/taking-over-a-project
Cleaning up a large, legacy Java project
https://stackoverflow.com/questions/690158/how-do-you-learn-other-peoples-code
Also, this book might help: Working Effectively with Legacy Code
"Patience and fortitude conquer all things." - Ralph Waldo Emerson
I would recommend you to start with the debug as well so you can go through the program step by step.
Documentation:
If you have documentation, it’ll be helpful. But it can be a pitfall, as much documentation is out date, they can be misleading you.
Bugfix:
You could start with bugfix or new feature implantation. Start work with small scope, it’ll be easy work. During the bugfix, you could understand the code more and more.
Baseline the code, I generally would use git
Do a build of the application
Run it.
If baseline fails build or process is too complicated, create a branch and fix it
Create a branch and modify a string or something that would show some visible change if you modify the code.
If Javadocs are not created via ant or build files, create a new branch to do this.
If there is no JUnit test cases (or if there are but they don't work), create a branch and fix it.
Create a new branch to do the merge.
The following is if you're using Eclipse or similar product
If you're the only developer, create a new branch and set up project settings for code formatting and cleanup. Then execute the code formatting and cleanup. This would allow you to have a more stable baseline for future work. If not, try to coordinate with others.
Install FindBugs, Checkclipse, PMD to do some simple checks on the code base. Looking at WTFs sometimes will give you a better idea on how things are working (or not)
Install Eclemma and see how much of the code is actually tested.
Recently we planned to use checkstyle plug-in in our project. As a part of this exercise existing code has to be cleaned up to comply with checkstyle rules. We have found that close to 18K violations correspond to absence of javadoc comments in class files.
My question is, is there any plugin or tool which i can use to generate javadoc comments for the entire artifacts?
I had a look at JAutodoc , and I would
like to know whether there is anything better than this.
Your real code quality will go down by generating JavaDoc, even if the CheckStyle score goes up. Generated JavaDoc can only reflect what is already obvious from the code, it adds volume which decreases readability and it probably (depending on you tool) will not keep itself up to date, adding a maintenance burden and leading to inconsistencies after the code evolves.
Don't let yourself be badgered into cluttering your code. The CheckStyle violations should be taken as hints, not absolute iron-clad rules. Adding sensible JavaDoc takes time and understanding of the code, you should make policy for creating it from now on in all new code, and add it in any existing code when it gets refactored.
BTW: you don't have to JavaDoc everything. I personally don't JavDoc default getters/setters, overrides or methods/fields with self-explanatory names (which I strive for). I always JavaDoc top level entities (interfaces, classes and enums) and put non-JavaDoc comments on blocks of code that do something complicated.
If you create a NetBeans project you can ask it to automatically generate the missing skeletons for you. A simple right mouse click on the project to select the menu item and you will have all the missing skeletons in place.
Another tool (costs money, but well worth it) is the commercial version of Jalopy from triemax which is an excellent code formatter (the developer is super responsive and adds new features relatively quickly when requested).
Had the same problem recently. We just changed the checkstyle configuration file to set missing javadocs only as warnings until our contributors have included the missing docs.
How to do this is decribed here link text, or you can use the eclipse checkstyle plugin which provides a GUI interface.