• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documenting class files in the final package

 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
My assingment instructions states that I must document the names and high level descriptions of all submitted files in the README.TXT.
I would like your opinions on how to document anonymous inner classes named like Foo$1.class, Foo$2.class ?
thanks
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Assuming your own instructions don't say otherwise: don't include any separate .class files in your submission. All the .class files should be bundled in a single executable jar file. (Which in turn is bundled in another jar file, along with everything else you submit.) No need to document any of the class files, anonymous or otherwise.
 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Jim,
Thank you. Your suggestion is the most reasonable option, but look at what my assignment says:

When you submit your assignment, you should provide the following parts.
1) Full source and object code, including new classes, modified versions of supplied classes, and copies of supplied classes that were not modified. These should be in an appropriate directory structure along with the classfiles. You may use JAR files to contain groups of elements of your submission as you deem appropriate, for example, to support the execution of your programs
...
4) A README.txt file that describes to the examiner the following information in exactly the order listed:
a)...
b)...
c) The names of the files you have submitted, with a note of their location in the directory structure, and a high level description of the purpose of each.

Help me clarifying this: Dont you think that the highlited sentences are implying that I should add and document
all class files?
thanks again
[ July 07, 2003: Message edited by: Marcos Motta ]
 
Jim Yingst
Wanderer
Sheriff
Posts: 18671
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I guess so. It's a silly requirement in this case, but it does seem to be a requirement for you, so what the heck. I wouldn't spend too much time on my high-level descriptions for the class files though. Maybe something like:

There really isn't anything else that people need to know about these, IMO. If they want to know more, they should be looking at the source. The description for Foo.java should have more detail, but keep the class file descriptions pretty minimal, IMO.
[ July 07, 2003: Message edited by: Jim Yingst ]
 
Marcos Motta
Ranch Hand
Posts: 56
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks a lot Jim
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12014
220
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Marcos
I paid more attention to the fact that we are allowed to "use JAR files to contain groups of elements", and that is what I did: all *.class files were in one of my two jar files. Full source code was in the individual files in their appropriate directories when the submission jar was extracted. All object files were in one of the jar files - they were in the appropriate directory structure, however they (and the directory structure) were in a jar file.
And for the requirement taht The names of the files you have submitted, with a note of their location in the directory structure, and a high level description of the purpose of each." - note the "high level" statment. I kept all descriptions ultra high level.
I didn't loose any points for documentation, and I only lost 1 point in the "general considerations" section.
Regards, Andrew
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic