Win a copy of Python Continuous Integration and Delivery this week in the Python forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Bear Bibeault
  • Paul Clapham
  • Jeanne Boyarsky
Sheriffs:
  • Devaka Cooray
  • Junilu Lacar
  • Tim Cooke
Saloon Keepers:
  • Tim Moores
  • Ron McLeod
  • Tim Holloway
  • Claude Moore
  • Stephan van Hulst
Bartenders:
  • Winston Gutkowski
  • Carey Brown
  • Frits Walraven

Java by Comparison: broken down by major types?  RSS feed

 
Ranch Hand
Posts: 33
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think that  Learning by Example is a great idea.   I see there are 70 examples.  Is it broken down by major types, for example, by certain algorithms? (Optional second question: Who or what are your sources and mentors?
Thanks! Thomas Zink
 
author
Posts: 20
6
IntelliJ IDE Java Ruby
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Thomas,

excellent question!

The examples are grouped by type: code style, comments, error handling, testing with JUnit 5, OO-design, functional programming with Streams and Optional, and last but not least, things you encounter in the real world like concurrency. Have a look at the table of contents at https://pragprog.com/book/javacomp/java-by-comparison

The main source is our experience teaching Java at University. We did this for over six years to literally hundreds of students. And we had to mark the assignments that the students had to hand in, and they had to hand in a lot. We've read tens of thousands of lines of code during that time, and we learned what mistakes Java beginners make, where they struggle, and how to help them overcome their issues - namely with clear before/after examples detailing why something is problematic, and why the solution is really a solution. From this experience, the idea for a knowledge base came into being, but a knowledge base that acts like a mentor with infinite patience, helping the students with clear and concise examples how to improve their code, one item at a time. And that's the story of this book, in short. :-)

We even published a paper on "Teaching Clean Code": http://ceur-ws.org/Vol-2066/isee2018paper06.pdf

Best,
Simon
 
Thomas Zink
Ranch Hand
Posts: 33
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks for your answer,
I will check it out.
 
Sheriff
Posts: 13147
218
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This is awesome!

Do you think there would be any interest in having professionals from the industry get involved in some of those reviews? I would definitely sign up for that.

Thanks to Campbell for giving me a heads up about this.
 
Simon Harrer
author
Posts: 20
6
IntelliJ IDE Java Ruby
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Junilu,

awesome idea to integrate code reviews from professionals as well. We haven't thought of this before, maybe because we thought it's hard to get professionals to work pro bono on student assignments - maybe that's just not the case.

I am sorry to say that I no longer work/teach at the University, but moved to industry/consulting a few weeks ago. If you like, I can pass on your contact to my successor at the University of Bamberg, Germany. Just email me your contact info to simon.harrer@gmail.com

For the examples in the book: we had a lot of professionals as reviewers, making sure that the items are relevant for developers in industry as well. If you want to be a reviewer of any further edition of the book, reach out to me as well. :-)

Best,
Simon

 
Junilu Lacar
Sheriff
Posts: 13147
218
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks, Simon.

I have made a couple of attempts in the past in trying to get better alignment between academia and industry, one with limited success and the other I consider a dismal failure. The one where I had some success was started right here at CodeRanch when a CS professor from a university in Charleston, SC posted a question. That eventually led to me giving a webinar and an onsite workshop about getting academia and industry better aligned. That was in March 2017 and I've been meaning to get back with the professor but haven't had the chance to do so. Seeing this book promo, however, I think I will do just that and recommend your book. I'll invite him to post something while you're here. You and he might have some interesting things to share with each other and all of us.

The failed attempt was me contacting professors at the school my son attends. I was frustrated with the way I saw he was being taught Java (using static methods, no OO concepts until almost the end of the term) and the lack of instruction on clean coding and other industry practices like automated unit testing. They wouldn't even let him use GitHub because it violated department policies that were meant to curtail plagiarism, which is kind of diametrically opposite to what people in the industry do, openly sharing work with each other for the betterment of the community. My son ended up having to use a local git repository instead because I insisted he not listen to the school's (frankly dumba$$) recommendation to copy his work to a thumb drive. Yes, they really suggested that on the course website. So 1980s. Bottom line, the responses I received were basically "Thanks, but no thanks. We think we're teaching them fine since our graduates are getting hired by really good companies like blah blah blah."

Anyway, I will send out those emails shortly. Thanks again.
 
Marshal
Posts: 63314
205
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Junilu Lacar wrote:. . . a couple of attempts . . . trying to get better alignment between academia and industry . . .

I knew about those attempts of Junilu's, so I was sure he would like to see your paper after reading the first few sentences.

Obviously, as I suspected, there are places where they do teach up to date coding. But, how are students and applicants supposed to know the difference?
 
Greenhorn
Posts: 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you for this book. I am excited to read it.

I saw a section in this book. "Document Using Examples". I understand that it is better to document by example as was the case of the regular expression pattern.
But isn't it even better to document by unit tests and avoid documentation as comments altogether.
 
Campbell Ritchie
Marshal
Posts: 63314
205
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Welcome to the Ranch

Please explain a bit more what you mean about reducing documentation by comments.
 
Simon Harrer
author
Posts: 20
6
IntelliJ IDE Java Ruby
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Kamal,

I get your point. We discussed exactly that when we wrote that comparison. Our answer: you should do both, actually.

It's not like test cases can substitute for comments. The comment should contain just a few examples. The test cases, however, should be extensive, covering many different possibilities.

Also think about what you are doing when you quickly want to use a method or field and would like to know something about that. How often have you looked at the documentation, and how often have you really searched for the test cases? From our experience, documentation is, and will be, the first step in the search for info.

Hope this helps,
Simon
 
Junilu Lacar
Sheriff
Posts: 13147
218
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Kamal,

Not all comments are bad or unnecessary although I have seen many that are. I think the authors explain the difference between good comments versus bad comments in the book. My rule of thumb is that if you can refactor the code to be so expressive as to make a comment redundant, then that's good. There are situations where it is useful to add comments that can help explain why something was done though. Comment that clarify the kind of things that can't be explained well through tests, such as why one algorithm was chosen over another, for example. It's all about creating context for the reader of the code, so they can get a good idea of what was going on in the programmer's mind when the code was written.
 
Junilu Lacar
Sheriff
Posts: 13147
218
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Simon Harrer wrote:Also think about what you are doing when you quickly want to use a method or field and would like to know something about that. How often have you looked at the documentation, and how often have you really searched for the test cases? From our experience, documentation is, and will be, the first step in the search for info.


Perhaps so, but comments are often unclear, incomplete, unreliable, and possibly even obsolete. Comments often don't change along with the code. Unit tests, on the other hand, have to change, unless you want to leave them disabled or failing.

I coach teams to look at the unit tests first. When code is messy, tests usually get more attention than comments and are therefore relatively more reliable.
 
Simon Harrer
author
Posts: 20
6
IntelliJ IDE Java Ruby
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I agree. If you have messy code, focus on the tests. They give you much more value than in comparison to writing comments.

But I fight against this mantra of saying that comments are bad all of the time. That's simply not true. They have their issues, yes, but they can be tremendously helpful: the JavaDoc of a method/class/field is directly shown in the IDE, that's what makes them just so useful. And having a quick usage example is really really valuable.

In enterprises, we have comment requirements - and those are the real problem. When we are forced to comment something that's obvious from the actual underlying code - and when the code changes, we often forget those comments we don't really value. But from my experience, you typically can't go wrong by documenting with examples. Often, a single example might suffice whereas the tests cover tens of different examples. But that single example already helps the developer using your method, and when you start to value those examples, you'll try to keep them in sync.

One remark regarding looking for tests first. I am not really sure this works out in practice. Often, you only quickly want to get to know how to use that method, and for that, you have to a) search for the tests, b) sort through all the tests to find the correct one, and c) try to understand what the test is doing. Perhaps they are using another test framework, or many helper classes that makes it hard to read the test; or even a lot of before/setup methods to prepare the test. I am not sure whether that is really productive; especially for the 80% case of getting a feeling how to use that one method, not reading the full specification of it with all its edge cases.

Best,
Simon

 
Junilu Lacar
Sheriff
Posts: 13147
218
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Here's what I have seen in practice:

1. Examples in documentation either in the form of JavaDocs or a wiki page can be very helpful if they are up-to-date.

2. Busy developers seldom have time to keep documentation comments up-to-date and they rarely do. Take examples from documentation with a grain of salt and always try them yourself to be sure they work as advertised.

3. If you're writing a utility or library for general use, there's more incentive to give examples in documentation comments and keep them current. I trust those kind of comments/examples more than I do other kinds of documented examples. If you have them, that's great.

4. If developers follow naming conventions and project structure and directory layout conventions, you can usually find tests related to a class fairly quickly. I always look for a src/test/java folder because most projects I work with use Maven and the layout is pretty much a de facto standard. IDEs can also do a lot of the heavy lifting for you by finding the references to a method, which are in turn organized and sorted by location in the project structure.
 
my overalls have superpowers - they repel people who think fashion is important. Tiny ad:
Become a Java guru with IntelliJ IDEA
https://www.jetbrains.com/idea/
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!