Solved

Code Documentation Requirements

Posted on 2006-11-06
3
162 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

Live: Real-Time Solutions, Start Here

Receive instant 1:1 support from technology experts, using our real-time conversation and whiteboard interface. Your first 5 minutes are always free.

Question has a verified solution.

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

Suggested Solutions

Title # Comments Views Activity
topping3 challenge 14 78
How  do I get an older program to run in Windows 10? 20 110
C# Error - Add Failed 12 87
C# application error "Parameter Is Not Valid". 3 94
Whether you've completed a degree in computer sciences or you're a self-taught programmer, writing your first lines of code in the real world is always a challenge. Here are some of the most common pitfalls for new programmers.
Whether you’re a college noob or a soon-to-be pro, these tips are sure to help you in your journey to becoming a programming ninja and stand out from the crowd.
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 …
With the power of JIRA, there's an unlimited number of ways you can customize it, use it and benefit from it. With that in mind, there's bound to be things that I wasn't able to cover in this course. With this summary we'll look at some places to go…

815 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

8 Experts available now in Live!

Get 1:1 Help Now