• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documentation question

 
Victor Bucutea
Ranch Hand
Posts: 43
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Howdy Guys,


I'd like to know what do your Javadoc comments contain?
Do they contain design choices ( advantages/ disadvantages and descriptions ) like the ones below, or they just describe the role of the class and it's usage?

Rephrase.
The javadoc comments should contain comments that another programmer might use to understand those classes, or comments that help the assessor understand the code and the decisions?


 
Roel De Nijs
Sheriff
Posts: 10662
144
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Victor,

My opinion:
* javadoc = should contain comments that another programmer might use to understand those classes
* choices.txt = comments that help the assessor understand the code and the decisions

Kind regards,
Roel
 
Victor Bucutea
Ranch Hand
Posts: 43
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yep ...


I was kinda expecting that answer . The reason why i asked is that in Andrew's book javadocs describe a lot of design choices.



Victor
 
Matheus Mendes
Ranch Hand
Posts: 68
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The reason why i asked is that in Andrew's book javadocs describe a lot of design choices.


Thats a good thing to be in the javadocs too. I mean, you don't need to describe why you choose RMI or why you want to design the GUI like that, but is good to describe how your architeture works. It's a good thing to others programmers read about a system that they will give support and maintenance.

For example, in the Andrew's book he describes how he read a register in the .db file and what the system do to ensure the data consistence.


 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic