Generically, some methods involve first writing a short description of what is to be done. Then a flowchart is made by referencing the description, and sometimes the flowchart is much more detailed. After that, pseudo-code might be written. At that point, not only is there enough to create documentation, but the feasibility of the program and potential amount of work to be done is determined as well. Though the actual code hasn't been written yet, a work flow has been created which is helpful when only a little bit of time can be spared at random intervals. Translation: gives direction and helps reduce wasted time running in circles.
A copy of the pseudo-code can easily be made into comments, perhaps by prepending each line with # or //. At this point, what needs to be written is usually obvious and the pseudo-code is replaced with real code. Sometimes the pseudo-code is left in place as a simpler explanation of the code, or expanded with an explanation of any "neat tricks" or potentially forgettable reasons for using certain techniques. In this way, code documentation is automatically built-in, or rather the documentation has become the foundation of the building.
The flowchart and particularly the pseudo-code will help in documenting the code itself, great for when the code is revisited later. A revised description based on the original (and maybe the flowchart) will help in documenting the feature, great for the end user. The whole process helps create direction and saves time later when everybody is trying to figure out how to use it, or inevitably figuring out how to modify it, or even whether it's needed any more.
And while programmers may not always make the best documenters for the end user, I've found it's always easier and more accurate if there is at least some sort of documentation provided by the programmer when someone else makes the attempt. Or at least, this is part of my experience having been on both sides.
Uhm, er, I'm not trying to tell anybody how to code or document... Like I admitted, there are many different ways, and the above is merely a generalization of one way to accumulate documentation when programming. It sounds like there is already a procedure in place which encourages documentation, and that's great.
Often, I've thought about putting some time to figure out how to make and maintain packages for fink, but have yet to figure it out from the documentation. That's likely because my experiences are different or lacking, and I haven't looked at that part of the documentation again lately. As a fink user, I'm very interested in seeing documentation and having it updated, so if anything, just take this as further encouragement, but please not as a lecture.
I appreciate the documentation that is available and it's gotten much better since the beginning. Who can ask for anything more? I feel very lucky and privileged to have fink available to use.
Thanks everyone. :-)
-- Thom
On Dec 10, 2003, at 12:31 PM, TheSin wrote:
<snip>
Also I believe that the -b switch for list and remove and purge isn't documented, and I don't think anyone wants me making docs, plus this documenting features before they are release is odd to me. I think we need a new documentation procedure.
---
TS
http://southofheaven.org
Chaos is the beginning and end, try dealing with the rest.
------------------------------------------------------- This SF.net email is sponsored by: SF.net Giveback Program. Does SourceForge.net help you be more productive? Does it help you create better code? SHARE THE LOVE, and help us help YOU! Click Here: http://sourceforge.net/donate/ _______________________________________________ Fink-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/fink-devel
