• Status: Solved
  • Priority: Medium
  • Security: Public
  • Views: 270
  • Last Modified:

Java Documentation

There is no doubt that all the experts in Java forum here are genius in Java programming and they can easily set up the environment, implement the business logic and deploy the application to Production environment.

But how many of them is actually documenting the J2EE application that they created? I am not talking about the JavaDoc but the Design Specification or Requirement Specification or any other specs.

Myself, personally, I sometimes ignore this part :). Sometimes, I can't think of the use of it. They said that it is for maintenance. Yes, it is true that the new J2EE developers coming and in fact they look at the codes instead of these documentations.

If you did, please let me know your opinion and which specifications template do you use? Did you explain the app in high-level? Did you explain each and every method in your J2EE app?

Just curious :)

David
0
suprapto45
Asked:
suprapto45
  • 7
  • 6
  • 3
  • +3
7 Solutions
 
objectsCommented:
Personally avoid it as it rarely gets maintained and quickly gets out of date.
The only reliable documentation is the code :) So times better spent writing good code.
0
 
mbvvsatishCommented:
i agree with you suprapto45. even i have the same feel.
i maintain the design specs, requirement spec...etc but when new developers join the project they actually look at the code and not the documents.

but one thing i can say based on my experience is
at times we get issues / bugs even after certifying the product by testing teams, BA's and client as well, which are actually not bugs but it is the way it works or its the actual functionality of the application.
In such cases these documents will be useful as a *documentary evidence* to prove that what ever is done is not a bug, but its the functionality.

one more thing is new developers may not use the design specs, requirement specs which are related to the business functionality, but can be useful for knowing current functionality while doing impact analysis for the new changes/requirements.

documents like technical architecture, assimilation/work flow documents will definately useful for the new developers in the project.
>>Did you explain the app in high-level?
yeah. ofcourse my assimilation/work flow document will be sufficient for this.

>>Did you explain each and every method in your J2EE app?
no, never. as and when they start the work they will come to know about the methods one by one.
if unknowingly any developer writes a new method which is already available. i will tell him about this during code reviews.
0
 
suprapto45Author Commented:
Thanks objects and mbvvsatish,

mbvvsatish, >>"work flow document will be sufficient for this"
Is it like a Use-case diagram where all the functional requirements are listed out in higher level (not in technical details)?
0
Technology Partners: We Want Your Opinion!

We value your feedback.

Take our survey and automatically be enter to win anyone of the following:
Yeti Cooler, Amazon eGift Card, and Movie eGift Card!

 
mbvvsatishCommented:
it contains both the techinical flow as well as functional flow listed in very high level.
0
 
suprapto45Author Commented:
Thanks mbvvsatish.

Will keep this thread open so other may express their opinions.
0
 
mbvvsatishCommented:
actually speaking you are correct.
it is just like a Use-case diagram where all the functional requirements are listed out in higher level.

but we have included the high level techinical flow as well for our convinence to mentor junior developers coming into the project.
0
 
mbvvsatishCommented:
ok.
i have added this thread to *PE Notifier*. lets see if we get any other opinions.
:)
0
 
suprapto45Author Commented:
>>"i have added this thread to *PE Notifier*. lets see if we get any other opinions."
Thanks :)
0
 
suprapto45Author Commented:
>>"we have included the high level techinical flow"
Anyway, what kind of diagrams do you use to represent the high-level technical flow?
0
 
mbvvsatishCommented:
pure uml diagrams.
0
 
suprapto45Author Commented:
I see. Then if I were you, I will use both sequence diagram (show the flow) and package diagram (show the components).

Thanks.
0
 
mbvvsatishCommented:
good suggession.
but i think if we include both sequence diagram and package diagrams it will more of a detailed document than a high level document. any way if developer what to look into those detailed diagrams we alread have LDD's(low level design docs) for that.
0
 
kannan_ekanathCommented:
Ok,
Let me put my thoughts here. You have a web application, now there could be two types of documents
a) User Document : Where an end -user needs to be told how to use the application, configure bits and pieces of it. You typically get a Tech Writer (believe me Core Developers are bad at these), make her write a *BUSINESS* document. Note that I emphasize the word *BUSINESS* because It shouldnt have terminologies like Objects, Classes etc. It should be least bothered about the fact that you are using Struts etc. It should serve to tell you the *HOW* the app is intended to be used and not the *HOW* the app works internally

b) Design Document : The second type of documentation is what we are talking here. The all so infamous Design Document, is not *INTENDED* for an end user. (I guess everyone has to agree with me on this). Now the moment we say that the audience is a *reasonably technically equipped* developer, the question arises as to Whether he is better off reading the code, or reading the design doc and then the code. There are umpteen links to tell you that if you follow some basic coding conventions you are much better off straightaway reading your code, instead of the design documentation which really serves nothing. Upfront Huge Design (with lots of time spent) is considered a crime in some programming principles. If you still want links on why Code is better than the design document read them,

http://en.wikipedia.org/wiki/Extreme_programming (god of all links)
http://www.agilemodeling.com/essays/agileModelingXP.htm
http://www.acm.org/chapters/princetonacm/downloads/extreme_agile.html
0
 
reach2piyushCommented:
>>Design Specification or Requirement Specification or any other specs.

Requirement Specification - Normally Biz Analyst wrote it for Techies, So this is something I always get before starting coding in one form or the other
Design Specification - (Normally just Class diagrams & Sequence Diagrams) Found very handy for verifying the architecture, We normally skip the obvious or the repeated modules. & always draw it before coding & normally is not updated or kept for new developers

During the maintenance cycles of a project, we had problems with Knowledge transfer whenever a member moves out,
So for maintenance help, we started documenting something we called as Application Handbook, it was catalogued features wise & used to contain the list of files & debugging aid, a bit of design explanation for a given feature
0
 
kannan_ekanathCommented:
0
 
kannan_ekanathCommented:
My Personal Experience is in the current project, we have a "Business Analyst" whose job is to talk to customer and find out what they want. He then consults the UI experts and hands the developer a mockup and explains it.

Developer codes keeping in mind that Instant feedback is most important, and hence getting the APP to work minimally is the first and foremost concern. Once the APP is up, the Business Analyst, works on it, and *invariably* points out the things that he dint want to work like the way implemented. (Note until this point, some functionalities may not be very performant or the code may not be very clean). The developer now corrects them with sole intention to *make it work*, now he shows the demo.

Analyst is happy and points to the user, In the meantime the smart developer knows that he just got it barely working and so he works on improving the code, making it cleaner (using refactoring) without breaking the app :)

Agenda
a) Make it work
b) Make it fast (In the BackGround :) )
c) Make it clean (In the BackGround :)  use refactoring)
0
 
suprapto45Author Commented:
Thanks kannan_ekanath and reach2piyush,

Really appreciate your views :)
0
 
Mayank SAssociate Director - Product EngineeringCommented:
Depends on what kind of documentation you want. For developers who're gonna maintain/ enhance the code, the Java docs are definitely required because you know what the attrition rate in the software industry is like (at least in some countries ;)). And in order to match it with the requirements and design, you're gonna need all the static/ sequence diagrams. But you would need to prepare other design and program-specification documents too, which would be based on your company's or client's standard templates, and that would differ for you and me. That's what CMM level 5 is all about :)
0
 
suprapto45Author Commented:
Thanks to all of you :).

Appreciate that.

David
0

Featured Post

Concerto's Cloud Advisory Services

Want to avoid the missteps to gaining all the benefits of the cloud? Learn more about the different assessment options from our Cloud Advisory team.

  • 7
  • 6
  • 3
  • +3
Tackle projects and never again get stuck behind a technical roadblock.
Join Now