Solved

Code Documentation Requirements

Posted on 2006-11-06
3
160 Views
Last Modified: 2010-04-16
Dear Experts:

I have a group of coders who are currently working on development of a large web based application.  I would like my group of programmers to document the application they are coding in such a way that in addition to commenting their code, they produce a document that would be of asssistance to other coders in the fututre that will be working on modifying and customizing the application.  In a sense, a document that will be used to navigate the code base of the application.

Is there any methodologies that could be followed to produce such a document?  If I were to list out requrirements for the document, what should I specify?
0
Comment
Question by:superfly18
3 Comments
 
LVL 19

Accepted Solution

by:
VoteyDisciple earned 125 total points
ID: 17881326
I don't think this directly answers your question, but I'm a big fan of the kinda-make-believe "phpdoc" syntax if you're using PHP.  Basically this works just like Javadoc where class and method documentation can be automatically pulled out to make a handy webpage.  I've seen a number of tools to do this with PHP as well (Google will be as good at recommending one in particular as I, however).

That's not to say you wouldn't want a Systems Manual or other similar out-of-code documents, but I've found just having the aggregated documentation for the code pulled out and easy to browse goes a long way toward being able to understand a system.


By now I wouldn't be surprised if similar tools existed for other web languages as well.  I know .NET has its own XML syntax for doing this, for instance.
0
 
LVL 24

Expert Comment

by:SunBow
ID: 17883057
Step one is what are requirements. For example, you begin with files and fields with some constraints. The output is likely intended for a specific audience, has anyone bothered to ask them what they think product should look like (not do).

Chart how thing flow from one stage to another. From one system to another. Jot note about conversions done, directions and changes in direction.
0
 
LVL 1

Author Comment

by:superfly18
ID: 17883382
This happens to be a JSP development project.  There actually is a detailed specification put together.  Despite how things are specied, their actual implementation may mainifest itself in many different forms.  The real question here is that, say in five years someone is asked to develop a customization to the application, or modify it, perhaps significantly, and the original development team is not available.  What would the breadth of the documentation include that the new development team would like to see to be able to understand and navigagate the code base.  
0

Featured Post

What Security Threats Are You Missing?

Enhance your security with threat intelligence from the web. Get trending threat insights on hackers, exploits, and suspicious IP addresses delivered to your inbox with our free Cyber Daily.

Join & Write a Comment

Suggested Solutions

Go is an acronym of golang, is a programming language developed Google in 2007. Go is a new language that is mostly in the C family, with significant input from Pascal/Modula/Oberon family. Hence Go arisen as low-level language with fast compilation…
Does the idea of dealing with bits scare or confuse you? Does it seem like a waste of time in an age where we all have terabytes of storage? If so, you're missing out on one of the core tools in every professional programmer's toolbox. Learn how to …
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 …
In this fifth video of the Xpdf series, we discuss and demonstrate the PDFdetach utility, which is able to list and, more importantly, extract attachments that are embedded in PDF files. It does this via a command line interface, making it suitable …

747 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

9 Experts available now in Live!

Get 1:1 Help Now