Solved

Java Documentation

Posted on 2006-11-14
19
256 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
PRTG Network Monitor: Intuitive Network Monitoring

Network Monitoring is essential to ensure that computer systems and network devices are running. Use PRTG to monitor LANs, servers, websites, applications and devices, bandwidth, virtual environments, remote systems, IoT, and many more. PRTG is easy to set up & use.

 
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
 
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:Mayank S
Mayank S 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

Netscaler Common Configuration How To guides

If you use NetScaler you will want to see these guides. The NetScaler How To Guides show administrators how to get NetScaler up and configured by providing instructions for common scenarios and some not so common ones.

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

Suggested Solutions

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…
Java functions are among the best things for programmers to work with as Java sites can be very easy to read and prepare. Java especially simplifies many processes in the coding industry as it helps integrate many forms of technology and different d…
Viewers learn about the third conditional statement “else if” and use it in an example program. Then additional information about conditional statements is provided, covering the topic thoroughly. Viewers learn about the third conditional statement …
Viewers will learn about the different types of variables in Java and how to declare them. Decide the type of variable desired: Put the keyword corresponding to the type of variable in front of the variable name: Use the equal sign to assign a v…

770 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