• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

commenting code/deprecated methods

 
vladimir levin
Ranch Hand
Posts: 45
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I removed the deprecated methods in the Data class. Does anyone have suggestions about commenting such changes to the supplied code? I put in a short comment to the effect that the call to the deprecated method had been removed. The code that is supplied does not seem to have any in-line comments at all...
The instructions say:
The code itself should be as clear as possible,
and "obvious" comments should be avoided.
I don't want to be pedantic, but is putting such comments as I mentioned above being too "obvious" or does it make sense? Ahh... It is so frustrating writing for certification... all sorts of silly issues come to mind and worry my poor brain.
Vlad
 
Andrew Spruce
Greenhorn
Posts: 21
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I have exactly the same problem.
Fiddly little things you think may annoy the examiners, but feel should be highlighted to explain yourself.
I have commented out using one line style comments [//].
With a brief explanation : deprecated !
Does look untidy though.
Maybe I worry too much ??
 
Tom Peillon
Greenhorn
Posts: 9
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think the appropriate place to document this is in the design document, not the code.
Whilst it is common practice for many programmers to leave old code commented out in source files in case they need to revert, I don't think this can be regarded as good practice.
 
vladimir levin
Ranch Hand
Posts: 45
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
It's a dumb little detail... sigh. Keep in mind that as far as
I can tell from my assignment, there is no design document to
write. You have to write user documentation, and supply a
Javadoc... but but the Javadoc isn't true design documentation.
I would like to supply a document which basically explains
all the major decisions I've made. I don't know if I will do that
however, since it is not specified as a requirement in my
assignment. For now I have a simple comment that explains that
a deprecated method such and such was replaced with such and such
non-deprecated method...

Vlad
 
Tom Peillon
Greenhorn
Posts: 9
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Your assignment must be different from mine.
Mine specifies that a file should be submitted documenting major design choices.
 
Matt DeLacey
Ranch Hand
Posts: 318
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yes, mine too. The absence of this file would constiture failure I would think. It's hard to imagine them NOT asking for this, as it seems like this i a major POINT of the project. You might want to go back and read the specs very carefully.
With Respect,
Matt DeLacey
 
vladimir levin
Ranch Hand
Posts: 45
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Matt, I re-read my assignment more carefully. My assignment
also specifies a design document is required in the
"deliverables" section. Thanks for the tip.
Vlad
Originally posted by Matt DeLacey:
Yes, mine too. The absence of this file would constiture failure I would think. It's hard to imagine them NOT asking for this, as it seems like this i a major POINT of the project. You might want to go back and read the specs very carefully.
With Respect,
Matt DeLacey

 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic