Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

NX: Bodgitt and Scarper: may I modify the javadoc of the interface DB.java?

 
Ellen Zhao
Ranch Hand
Posts: 581
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
just started working on the Bodgitt and Scarper assignment. There is a given interface:

In order to generate a decent documentation later, I modified the javadoc of this file this way:

I didn't modify the code.
My worry is: Will that lead to "automatic failure?". Because I've changed the original file. Thanks in advance for any suggestion.
Regards,
Ellen
 
Bharat Ruparel
Ranch Hand
Posts: 493
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello Ellen,
Automatic failure implies testing with automated software which to me, means that as long as you are not changing the "code" piece of the interface, you should be OK, otherwise, there will have to be a very clear statement from Sun for us warning us not to TOUCH it. I don't see any problems with you "beautifying" the interface to make it more readable and consistent with the rest of your code. IMHO.
Regards.
Bharat
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This is something that's probably OK, but a strict reading of the requirements implies that Sun could fail you for this, even though that would be really silly, and seems unlikely. You definitely should not change any signatures at all. Adding javaoc may well be OK. However I'd avoid it; they provided the DB interface; if it's poorly documented (or rather, not documented at all as far as javadoc is concerned) that's not our fault. In my own design, I have created an EnhacedDB interface which extends DB and adds a few extra methods which I found useful (most importantly, a getMetaData() which allows me to make the DB more generic). Since I have this new interface, I take the opportunity to add javadoc to the methods there while leaving the original DB untouched. I even retain the complete lack of indentation in the DB interface Sun provided.
[ September 29, 2003: Message edited by: Jim Yingst ]
 
Chris Harris
Ranch Hand
Posts: 231
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
I have decided to change the javadoc in DB.java because the assignment says :
javadoc style comments must be used for each element of the public interface of each class.

This goes against the requirement that no supplied class can be changed. So in theory I could fail because changes the supplied code but if don't change it I could fail because I have not added javadoc comment.
If Sun were going to be hard then no one would pass
Chris
[ September 29, 2003: Message edited by: Chris Harris ]
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Chris - good point. Though we can get around it in this case because technically DB isn't a class, it's an interface.
Then there's another requirement:
you must not submit any code that is not your own work

That one's going to be tough to follow here.
So yeah, some requirements are just impossible to follow literally; we do the best we can. If you can find a practical way to follow the requirements exactly, do so; if not, find the best compromise you can. In my case, I already wanted another interface for other reasons, so it was easy for me to add javadoc to that enhanced interface, and leave the original alone. If I hadn't had the other interface, I might well have added javadoc to DB, because the interface is pretty important, and I think the need to document it is greater than the need to leave it unchanged. I think you can justify either position.
 
Ellen Zhao
Ranch Hand
Posts: 581
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Required Interface
Your data access class must be called "Data.java", must be in a package called "suncertify.db", and must implement the following interface:
...

My understanding to this statement is: my Data.java has to directly implement the interface DB.java, and the job of accessing data has to be exclusively implemented in the Data.java. I don't even dare to create any interface like the EnhancedDB.java or any class like DBAdapter.java....therefore the importance of the documentation of the DB.java is raised. That's why I modified the javadoc there. If I am free to do things like Jim did, I will definitely leave the file untouched. :roll:
Regards,
Ellen
 
Ellen Zhao
Ranch Hand
Posts: 581
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Nah Jim,
You added your new post while I was writing my follow-up

Regards,
Ellen
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
My understanding to this statement is: my Data.java has to directly implement the interface DB.java, and the job of accessing data has to be exclusively implemented in the Data.java.
I disagree only with the "directly" - I don't see any reason it needs to be direct.
You added your new post while I was writing my follow-up

You've got to be quick on the draw, here in the old west.
 
Chris Harris
Ranch Hand
Posts: 231
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
I agree with Ellen from the requirement
Your data access class must be called "Data.java", must be in a package called "suncertify.db", and must implement the following interface:

It is too risky to extend DB.
Chris
 
Philippe Maquet
Bartender
Posts: 1872
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Jim,
I agree with Ellen and Chris, it's too risky to extend DBAccess.
Mmh, I am sincere - there is no relation with our discussion about 2-tiers/3tiers.
I understand why you did so, but I didn't dare to do it.
So my design is warped (OK, I accept it) but it follows the letter of the instructions :

Best,
Phil.
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
If you think so, OK. But "implement" is a very well-defined concept in Java. "Any class that implements the declared interface is also considered to implement all the interfaces that this interface extends." - JLS 9.1.2. My Data class does implement the DB interface. And is there any possible practical reason why a customer would care whether implementation is direct or not? They might well care about whether (new Data() instanceof DB) evaluates to true or not, because they might have some other code somewhere that expects an instance of DB. My Data passes this test fine. Can you imagine any reason why the customer would care about whether the implementation is direct or not?
If you want I could even write

Though this should be considered totally unnecessary, IMO.
[ September 29, 2003: Message edited by: Jim Yingst ]
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ellen,
Going back to your original question, I did the Fly By Night Services assignment. In that we were given some really bad classes that we were told were "complete" excepect for 3 methods we had to add and two calls to deprecated methods we had to replace.
I went ahead and changed the JavaDoc for the provided classes as well, even though most people at the time seemed to feel that the "complete" statement implied that the provided classes should not be modified except for the specific changes requested.
My thought was that we were told to provide JavaDoc for all the classes and interfaces we were submitting, and if I didn't change the provided comments, the JavaDoc I submitted would be incomplete and/or incorrect.
I got 100% for my documentation.
Regards, Andrew
 
Philippe Maquet
Bartender
Posts: 1872
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Jim,

If you think so, OK. But "implement" is a very well-defined concept in Java. "Any class that implements the declared interface is also considered to implement all the interfaces that this interface extends." - JLS 9.1.2. My Data class does implement the DB interface. And is there any possible practical reason why a customer would care whether implementation is direct or not? They might well care about whether (new Data() instanceof DB) evaluates to true or not, because they might have some other code somewhere that expects an instance of DB. My Data passes this test fine. Can you imagine any reason why the customer would care about whether the implementation is direct or not?

I agree 100% with you. I just didn't dare Data to implement an extended DBAccess interface because I am an anxious guy (but you know that already ), and because I don't know how their automated check is performed.
If, after having tried to instantiate a Data by Class.forName("Data") it just checks "instanceof DBAccess", you are OK. But if instead it uses Class.getInterfaces() not recursively, it won't find DBAccess but your ExtendedDBAccess (I know it because I tested it). So, as I don't know, I am just cautious.
Now, let's say that their automated check tool is "smart", how will be the grader ?

Your data access class must be called "Data.java", must be in a package called "suncertify.db", and must implement the following interface: (DBAccess)

Reading "class Data implements ExtendedDBAccess", will he accept it for sure (I mean 100% sure) ?
I took so many risks in this assignment that I don't dare to take that one ...
Best,
Phil.
 
Philippe Maquet
Bartender
Posts: 1872
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ellen,
I did the same as Andrew (added javadoc comments to the provided interface).
By providing an interface, they provide its code, not its comments IMO. Just by copying, pasting and reformatting the interface to build a DBAccess.java, you'll change at least a few spaces, right ?
Best,
Phil.
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Regarding "how smart if the grader" (or the automated test): well, I have to assume they're at smart enough to be quelified to grade teh exam. I mean, there are all sorts of errors they could commit if they're stupid; I can't control that. I'm content to worry only about actual requirements, not stupid grader errors. If I get failed for the latter, you can bet Sun will hear about it, and so will everyone else.
By providing an interface, they provide its code, not its comments IMO. Just by copying, pasting and reformatting the interface to build a DBAccess.java, you'll change at least a few spaces, right ?
No spaces have been changed. I made sure I copied from the HTML source of the instructions, so that I got the raw text, not what my browser had chosen to render. Reformatting? No, my file has the same utterly crappy formatting they provided me with; I think it makes a nice contrast with the files I wrote, whihch look much better. I suppose there may have been some Unix/Windows conversion for line separators, but otherwise, I've made no changes. I agree it's probably not a problem if you insert javadoc comments; I just didn't see a need.
In Andrew's assignment inserting javadoc makes more sense, as he was already expected to edit other parts of the file, and it's not really clear what "complete" means in this context - perhaps it refers to methods but not their javadoc? In any event once you're forced to put some code into a file, you should really bring the whole file up to the same standards, IMO. Having javadoc on some public methods but not others just doesn't make sense, IMO.
 
Philippe Maquet
Bartender
Posts: 1872
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think it makes a nice contrast with the files I wrote, whihch look much better.


I suppose there may have been some Unix/Windows conversion for line separators,

but otherwise, I've made no changes

In any event once you're forced to put some code into a file, you should really bring the whole file up to the same standards, IMO.

In any event once you're forced to put some file into a file collections, you should really bring the file up to the same standards, IMO.
Best,
Phil.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic