Solved

Java Documentation

Posted on 2006-11-14
19
253 Views
Last Modified: 2010-03-31
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
Comment
Question by:suprapto45
  • 7
  • 6
  • 3
  • +3
19 Comments
 
LVL 92

Assisted Solution

by:objects
objects earned 50 total points
ID: 17944431
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
 
LVL 10

Accepted Solution

by:
mbvvsatish earned 150 total points
ID: 17944794
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
 
LVL 16

Author Comment

by:suprapto45
ID: 17944826
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
 
LVL 10

Expert Comment

by:mbvvsatish
ID: 17944837
it contains both the techinical flow as well as functional flow listed in very high level.
0
 
LVL 16

Author Comment

by:suprapto45
ID: 17944865
Thanks mbvvsatish.

Will keep this thread open so other may express their opinions.
0
 
LVL 10

Expert Comment

by:mbvvsatish
ID: 17944868
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
 
LVL 10

Expert Comment

by:mbvvsatish
ID: 17944875
ok.
i have added this thread to *PE Notifier*. lets see if we get any other opinions.
:)
0
 
LVL 16

Author Comment

by:suprapto45
ID: 17944920
>>"i have added this thread to *PE Notifier*. lets see if we get any other opinions."
Thanks :)
0
 
LVL 16

Author Comment

by:suprapto45
ID: 17944923
>>"we have included the high level techinical flow"
Anyway, what kind of diagrams do you use to represent the high-level technical flow?
0
Find Ransomware Secrets With All-Source Analysis

Ransomware has become a major concern for organizations; its prevalence has grown due to past successes achieved by threat actors. While each ransomware variant is different, we’ve seen some common tactics and trends used among the authors of the malware.

 
LVL 10

Expert Comment

by:mbvvsatish
ID: 17944929
pure uml diagrams.
0
 
LVL 16

Author Comment

by:suprapto45
ID: 17944939
I see. Then if I were you, I will use both sequence diagram (show the flow) and package diagram (show the components).

Thanks.
0
 
LVL 10

Assisted Solution

by:mbvvsatish
mbvvsatish earned 150 total points
ID: 17944953
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
 
LVL 5

Assisted Solution

by:kannan_ekanath
kannan_ekanath earned 150 total points
ID: 17945118
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
 
LVL 8

Assisted Solution

by:reach2piyush
reach2piyush earned 100 total points
ID: 17945120
>>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
 
LVL 5

Expert Comment

by:kannan_ekanath
ID: 17945122
0
 
LVL 5

Assisted Solution

by:kannan_ekanath
kannan_ekanath earned 150 total points
ID: 17945148
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
 
LVL 16

Author Comment

by:suprapto45
ID: 17945213
Thanks kannan_ekanath and reach2piyush,

Really appreciate your views :)
0
 
LVL 30

Assisted Solution

by:mayankeagle
mayankeagle earned 50 total points
ID: 17945934
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
 
LVL 16

Author Comment

by:suprapto45
ID: 17948158
Thanks to all of you :).

Appreciate that.

David
0

Featured Post

How to run any project with ease

Manage projects of all sizes how you want. Great for personal to-do lists, project milestones, team priorities and launch plans.
- Combine task lists, docs, spreadsheets, and chat in one
- View and edit from mobile/offline
- Cut down on emails

Join & Write a Comment

An old method to applying the Singleton pattern in your Java code is to check if a static instance, defined in the same class that needs to be instantiated once and only once, is null and then create a new instance; otherwise, the pre-existing insta…
Introduction This article is the first of three articles that explain why and how the Experts Exchange QA Team does test automation for our web site. This article explains our test automation goals. Then rationale is given for the tools we use to a…
Viewers learn about the scanner class in this video and are introduced to receiving user input for their programs. Additionally, objects, conditional statements, and loops are used to help reinforce the concepts. Introduce Scanner class: Importing…
Viewers will learn how to properly install Eclipse with the necessary JDK, and will take a look at an introductory Java program. Download Eclipse installation zip file: Extract files from zip file: Download and install JDK 8: Open Eclipse and …

757 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question

Need Help in Real-Time?

Connect with top rated Experts

22 Experts available now in Live!

Get 1:1 Help Now