The commented-out instructions that automatically appear in NetBeans-generated source code files looks like that shown in the next screen snapshot.
The text states:
/*
* To change this template, choose Tools | Templates
* and open the template in the editor.
*/
I see these annoying comments checked into the source code of projects I have worked in which NetBeans has been a heavily used IDE, but I was surprised to see how many people have made source code available on the web with these comments still there. I dislike these so much that I will check a file out of the source code repository, remove these lines, and check the file back in. Emilian's post points out that I'm not the only one that finds these annoying (he calls them a pollutant, which I think is a good description for them).
Emilian points out that NetBeans includes this in source code automatically in an effort to help developers learn how to better use the IDE and customize it, but adds: "This might sound like a great idea in practice but it's broken since most people won't change it." It is my opinion that this is the crux of the problem for this case in particular and for this category of things in general (one of the people commenting on Emilian's blog points out that Eclipse has similar features). I don't mind so much that the IDE includes these comments, but I cannot understand why one would leave them in place when checking in the code. Emilian suggests some alternative approaches that might be preferable to including commented text in the generated classes, but I'd be happy just to see end user developers remove these lines as an easy fix.
NetBeans's generation of Java servlets provides more specific automatically generated comments to help the developer working on a new piece of code. The next screen snapshot shows a method called
processRequest that has a simple example implementation provided in comments. This is shown in the next screen snapshot:
Here is the generated code shown in the above screen snapshot.
/**
* Processes requests for both HTTPGETandPOSTmethods.
* @param request servlet request
* @param response servlet response
* @throws ServletException if a servlet-specific error occurs
* @throws IOException if an I/O error occurs
*/
protected void processRequest(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
response.setContentType("text/html;charset=UTF-8");
PrintWriter out = response.getWriter();
try {
/* TODO output your page here
out.println("<html>");
out.println("<head>");
out.println("<title>Servlet SomeServlet</title>");
out.println("</head>");
out.println("<body>");
out.println("<h1>Servlet SomeServlet at " + request.getContextPath () + "</h1>");
out.println("</body>");
out.println("</html>");
*/
} finally {
out.close();
}
}
I don't see many developers leaving the above generated code in place. This seems reasonable, but I wonder why this is different than the template instructions at the top of the source code which often do get left in place even as the code is checked into the source code repository.
Since getting serious about developing web applications with REST principles in mind, I often find myself not wanting NetBeans to automatically generate servlets that have the
@doPost and doGet methods automatically call a single method (processRequest in NetBeans 6.8 as shown above).The generated servlet code contains
doGet and doPost implementations as shown in the next code listing.
/**
* Handles the HTTPGETmethod.
* @param request servlet request
* @param response servlet response
* @throws ServletException if a servlet-specific error occurs
* @throws IOException if an I/O error occurs
*/
@Override
protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
processRequest(request, response);
}
/**
* Handles the HTTPPOSTmethod.
* @param request servlet request
* @param response servlet response
* @throws ServletException if a servlet-specific error occurs
* @throws IOException if an I/O error occurs
*/
@Override
protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
processRequest(request, response);
}
It's been a Java servlet tradition for several years to have these methods do the same thing, but the rising popularity of REST has reminded us that the HTTP methods GET and POST are actually very different things despite what the web browser might tell you.
Fortunately, NetBeans makes it really easy to change these templates. How does one do that? That is where that comment that typically annoys me so much when left in managed source code actually comes in handy. That comment told me how to do it: "To change this template, choose Tools | Templates and open the template in the editor." I can change the template for the servlet under "Web" in the Tools->Templates wizard. There I can remove the commented out text and even change the behavior of
doPost and doGet so that they don't call processRequest anymore (and I can remove processRequest altogether).What if you wish to remove the comment about how to edit templates? That is done by changing the template of choice (such as the template for Java Class, Java Interface, or Java Servlet) and removing this line:
<#include "../Licenses/license-${project.license}.txt">
Once you save the template with this line removed, that text will no longer appear in files created based on that template.
The longer I develop software (and more specifically the longer that I refactor and maintain existing code), the more I realize that I want my code base to be lean. I loathe dead code and useless comments (as opposed to useful comments). It is nice to be able to work with the NetBeans template mechanism to remove some of these automatically inserted pieces of code before they even have a chance to get saved in the code repository.
3 comments:
A better way would be to set your project's license, see Geertjan's blog.
Peter,
Thanks for the feedback. I think the approach you mentioned is a nice way of getting rid of the comments by simply changing the "Default License" to be empty. The advantage of that approach is that the change needs to be only made in that one spot rather than in each template for each type of generated source file.
I have blogged in more detail on this in a later post.
More concisely:
Removing Unwanted Lines from Netbeans File Templates
Post a Comment