Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakarta.ee-community] Pull Request for jakartaee-examples

Hi,

 

I just submitted an update with all the items Manfred asked me to address. In my comments to the updated PR I wrote:

 

“I do object to the request to remove comments from the pom file and the html file although I have complied. If the audience to these examples are experienced developers looking to see what's new in Jakarta then maybe you can make the case that commenting these files is superfluous. I contend that many of the users of these examples are students and new developers whom we have a duty to provide with as much information about what is happening in these examples as possible.”

 

I understand your point in your message but I worry about narrowing the information these examples can provide. My goal as a teacher is to enforce and re-enforce. I comment pom files, html files and all the other auxiliary files because I want to be certain that someone who reviews my code understands the choices I made in a file even if it not directly related to the goal of the example. In my html file I had:

<!DOCTYPE html>

<!-- TheLearningServlet Web Application

     Prepared by Ken Fogel

     Twitter: @omniprof

-->

<html>

 

    <!-- This is a basic, old style, html file that allows you to test GET & POST

         and shows you the curl command to test PUT & DELETE.

    -->

 

First I identified the application this file is part of and the author of the file, giving a plug to my Twitter handle. This is followed by a simple comment about  the style of this HTML file. I would have also liked to, but didn’t, explain the connection to the CSS file or even how the id value allows the test class to push buttons. Everything I do is usually a “teachable moment”.

 

My pom.xml comments are more extensive because my experience is that many pom files are unclear and many new developers create these files by rote or by their IDE without understanding them.

 

Going forward I will submit in the format that the project requires and likely follow up with a blog post and fully commented version in my repo.

 

Thank you for you time and while we may have a difference of opinion, thank you for your comments.

 

Ken

 

 

From: jakarta.ee-community-bounces@xxxxxxxxxxx <jakarta.ee-community-bounces@xxxxxxxxxxx> On Behalf Of arjan tijms
Sent: May 3, 2020 10:44 AM
To: Jakarta EE community discussions <jakarta.ee-community@xxxxxxxxxxx>
Subject: Re: [jakarta.ee-community] Pull Request for jakartaee-examples

 

Hi,

 

It starts to look better, thanks again. It's a slow process, I know, but bear with us ;)

 

For the project as a whole, all samples are intended to be quite ordered/categorised. So the example from Nishant fit in quite well -> JSP -> Lifecycle methods. Meaning it demonstrates a single concept.

 

With the "learning servlet" it's less clear from its name. In the bigger picture of the project, with dozens of Servlet examples, what does a "learning Servlet" practically mean? All examples are to learn from, and to demonstrate something is working on a specific Servlet implementation (this last part should not be forgotten).

 

In this case, it's a Servlet to which some simple requests are done via an .html file, where the tests use that .html file as well. Maybe "basicRequests" or "simpleRequests" would be a better name? 

 

I know in this case the name is hard. Your sample is quite like this one: https://github.com/javaee-samples/javaee7-samples/tree/master/servlet/simple-servlet 

 

Where maybe "simple servlet" didn't fully describe the purpose of the example either, but I think it's still a little bit clearer than "learning servlet".

 

Also, there's a lot of comments about how basic things work that are not necessarily related to what the sample is demonstrating. We could perhaps say that this is the initial sample everyone should look at, so that one has all those comments, but then we'd better put that in the readme.md. Otherwise it looks quite out of place if say 100 samples only have comments about what they are demonstrating, and then one random sample has comments explaining Maven, Java etc itself

 

TLDR; consider a better name for the "learning servlet", put in the readme.md that this sample is the initial one people could look at.

 

Hope this helps ;)

 

 

 

 

Kind regards,

Arjan Tijms

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

On Sun, May 3, 2020 at 1:24 PM Kenneth Fogel <kfogel@xxxxxxxxxxxxxxxxxxx> wrote:

Hi,

 

I believe I have addressed all the issues that arose from my first pull request and so a new one in waiting. If there is anything else you’d like me to do please let me know. And if you feel it’s not appropriate that’s fine too.

 

Ken

 


From: jakarta.ee-community-bounces@xxxxxxxxxxx <jakarta.ee-community-bounces@xxxxxxxxxxx> on behalf of omniprof@xxxxxxxxx <omniprof@xxxxxxxxx>
Sent: Wednesday, April 29, 2020 3:47:10 PM
To: 'Jakarta EE community discussions' <jakarta.ee-community@xxxxxxxxxxx>
Subject: [jakarta.ee-community] Pull Request for jakartaee-examples

 

Hi,

 

I have just submitted a pull request, my first ever, for jakartaee-examples. It consists of The Learning Servlet along with a minor error correction to the parent pom file. As requested it is in the same style as all other individual projects and does not use any external libraries. There is a simple test that deploys the web site and then clicks on a button to execute the servlet.

 

Feel free to make any suggestions or criticisms. I hope to submit more especially as I have figured out how to do it, finally.

 

Ken Fogel

 

 

_______________________________________________
jakarta.ee-community mailing list
jakarta.ee-community@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/jakarta.ee-community


Back to the top