this is the tool I meant - visDoc / ASDoc were these once the same? cant remember... Im having a slow day...
http://www.visiblearea.com/visdoc/ On 12/23/05, Merrill, Jason <[EMAIL PROTECTED]> wrote: > Where can I get ASDoc? Google seems pretty ignorant of it - at least as > a product or software tool. Or is it an internal-only product Adobe > uses? Or is it simply a Macromedia standardized HTML format for help > content? > > Jason Merrill | E-Learning Solutions | icfconsulting.com > > > > > > > > > > > >>-----Original Message----- > >>From: [EMAIL PROTECTED] [mailto:flashcoders- > >>[EMAIL PROTECTED] On Behalf Of JesterXL > >>Sent: Friday, December 23, 2005 10:56 AM > >>To: Flashcoders mailing list > >>Subject: Re: [Flashcoders] Faster code? > >> > >>Oh yeah definatly. Even though Natural Doc's syntax feels more > >>straightforward, ASDoc definately has the most beautiful output that > I've > >>seen to date. > >> > >>----- Original Message ----- > >>From: "Paul BH" <[EMAIL PROTECTED]> > >>To: "Flashcoders mailing list" <[email protected]> > >>Sent: Friday, December 23, 2005 10:53 AM > >>Subject: Re: [Flashcoders] Faster code? > >> > >> > >>1) I agree, that's why back to my earlier thing, I rarely comment - > >>what ASDoc does do however is provide a way of displaying things like > >>your method signature in a friendly HTML like manner, with a handy > >>index down the side. When I do comment, it would be to explain some > >>hackery, or something that wasnt obvious - within a function, this > >>wouldnt get picked up, if it was something like a paramenter only > >>being in an allowable range, I would comment that in a way that ASDoc > >>picks up... > >> > >>2)Hehe if I couldnt do that, it would be nirvana-esque... I never said > >>that this document wouldnt change - the key thing here is to make sure > >>that the change is captured in one place and one place alone... ie - > >>when business changes the specification, this is reflected in my unit > >>tests (as they are one & the same document), and thus my test suite > >>know about it straight away... > >> > >>On 12/23/05, JesterXL <[EMAIL PROTECTED]> wrote: > >>> 1. ASDoc just generates comments from your code. If your code > comments > >>> aren't up to date, neither is your generated asdocs. > >>> > >>> 2. If you could coerce a client to sign a document saying that > business > >>> requirements never change... hell dude, I'm hiring you fulltime to > work > >>> for > >>> me! > >>> > >>> > >>> ----- Original Message ----- > >>> From: "Paul BH" <[EMAIL PROTECTED]> > >>> To: "Flashcoders mailing list" <[email protected]> > >>> Sent: Friday, December 23, 2005 10:31 AM > >>> Subject: Re: [Flashcoders] Faster code? > >>> > >>> > >>> I'm so glad I opened such a juicy can of worms just before Christmas > ;) > >>> > >>> I just want to throw one more thing into the mix before I dissappear > off > >>> to > >>> numb > >>> my family reunion with hefty doses of alcohol... > >>> > >>> So, now I think my comments before about, erm comments still stand. > I > >>> see comments differently to documentation, so I'll just add my > >>> tuppence to this and retire to eat drink & be merry... > >>> > >>> I think some (many)? people dont document because they cant be > arsed. > >>> Why is this the case? We'll, again, I think it comes down to > changing > >>> requirements, and the fact that I hate having the same information > in > >>> two places, as at some point one will get out of date... > >>> > >>> How to manage this, and at the same time make your code easy to > >>> understand? > >>> > >>> This is how we are approaching it / looking to approach it... > >>> > >>> 1) Documentation of individual methods within classes is done using > >>> ASDoc which gets triggered whenever a file gets checked into source > >>> control -- your documentataion is generated from your class file, > and > >>> is *always* up to date with your checked in class file... > >>> > >>> 2) We are looking into using a thing called FIT (http://fit.c2.com/) > >>> What this does is tie in business requirements with unit tests. The > >>> business (ie the client) basically write their specifications (or > are > >>> assisted with it) in a word document. wherever a table is > encountered, > >>> this is interpreted by FIT as a unit test, and the test builder > writes > >>> a fixture to accomodate that test... What this means is that you are > >>> documenting your business logic in one place (rather than both a > specs > >>> document and a slew of unit tests) > >>> > >>> For me, the underlying principle is this -- DONT REPEAT YOURSELF -- > >>> it'll save you a whole truckload of hassles down the road... > >>> > >>> Pxx > >>> > >>> > >>> > >>> On 12/23/05, Hans Wichman <[EMAIL PROTECTED]> wrote: > >>> > Just to those that are reading this thread and wondering if > writing neat > >>> > documented code for clients (and payed for by clients) is an > illusion, > >>> > my > >>> > 2 > >>> > cents: > >>> > > >>> > we've been working on a project (complete virtual learning city) > in > >>> > flash > >>> > in which the client didnt really know what he wanted up front, > which we > >>> > tackled using a usecase-development/prototyping approach. > >>> > The object oriented design was by large thought up up front, the > >>> > conversion > >>> > of this design to AS2.0 was done bit by bit, using unit testing > etc. All > >>> > the while the specs where changing and we made > this-phase/next-phase > >>> > choices and did a small impact analysis for most of them. > >>> > During implementation most of the code was being documented > already > >>> > (during > >>> > or upfront), not using obvious what-does-this-button-do comments, > but > >>> > WHY-does-this-button-do-what-it-does comments. The internals > workings > >>> > may > >>> > change, but why-it-does-what-it-does usually doesnt. The client > now > >>> > requested ALL documentation to be delivered as a separate product, > most > >>> > of > >>> > which is already present and includes functional docs, technical > docs, > >>> > source docs, readers, etc. > >>> > This product will run for a number of years, currently 4 virtual > >>> > casestudies have been implemented and 50 more will be required > over the > >>> > next few years (casestudy == adventure game). A number of people > are > >>> > working on this project together, ussually not having a clue what > the > >>> > other > >>> > one does, they just agree on a common interface for example > between > >>> > client > >>> > and server (which is documented by examples mostly). > >>> > Lots of changes will probably be required, but since the code is > >>> > modular, > >>> > its clean (99,9%) and well documented, we can analyse what has to > be > >>> > refactored and what doesnt need to be. > >>> > > >>> > This is not to start up the discussion again whether or not to > document > >>> > your code, just to tell you that almost all our clients (our > company has > >>> > about 50 ppl and a lot of clients) request a solid design, solid > >>> > documentation and a copy of the sourcecode. Internally we are all > >>> > expected > >>> > to have a high standard and work on increasing this standard even > >>> > further > >>> > (for example by reading books such as 'code complete', taking > >>> > certifications, studying oo development). This is the same for > java, > >>> > php, > >>> > AS1, AS2, visual basic or c++ developers. > >>> > > >>> > Does the way we work slow us down? No. > >>> > Does the way we work cost us clients? Nope. > >>> > Does everything need to be documented? No ofcourse not. > >>> > Is this approach applicable to all types of projects? Nope. > >>> > Will we hire someone who is fast but does not document his crappy > code, > >>> > again? We surely wont, and we know becoz we review his code after > each > >>> > project. > >>> > > >>> > I do think lots of the arguments given here against documenting > are just > >>> > excuses in order not to have to, or a lack of skill in the oo > design > >>> > area. Rewriting and rewriting and rewriting (with or without > >>> > documentation) should make warnings bells go off in your head, > with or > >>> > without someone paying for it. > >>> > Can I do the same very cool things all the > non-documenting-guru/hackers > >>> > do? > >>> > Nah unfortunately not, but thats beside the point ;). > >>> > > >>> > When it comes down to it, I agree you have to pragmatic when > coding, not > >>> > everything we do has to have an academic standard, but you > shouldn't > >>> > grab > >>> > every opportunity to write crappy code with both hands either. > >>> > > >>> > Just my 2 cents... > >>> > H > >>> > > >>> > > >>> > At 08:51 AM 12/23/2005, you wrote: > >>> > >>I think it reflects the nature of flash and its history. > >>> > > Not to mention the diverse skillset of its developer-base. A > lot of > >>> > > people learned to write code in Flash, and the question of > whether > >>> > > they > >>> > > are doing it the "right" way or not is debatable. > >>> > > > >>> > >>In other words, as flash becomes a real software development > platform, > >>> > >>real development methodologies will become more important. > >>> > > That's really what it comes down to. As you start building > >>> > > longer-term > >>> > > projects and using standardized methodologies, these things > start to > >>> > > become more important. I still do the occasional one-off > animation or > >>> > > ad, > >>> > > but that's not where I spend the majority of my time these days. > >>> > > > >>> > >ryanm > >>> > >_______________________________________________ > >>> > >Flashcoders mailing list > >>> > >[email protected] > >>> > >http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > >>> > > >>> > _______________________________________________ > >>> > Flashcoders mailing list > >>> > [email protected] > >>> > http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > >>> > > >>> _______________________________________________ > >>> Flashcoders mailing list > >>> [email protected] > >>> http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > >>> > >>> _______________________________________________ > >>> Flashcoders mailing list > >>> [email protected] > >>> http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > >>> > >>_______________________________________________ > >>Flashcoders mailing list > >>[email protected] > >>http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > >> > >>_______________________________________________ > >>Flashcoders mailing list > >>[email protected] > >>http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > NOTICE: > This message is for the designated recipient only and may contain privileged > or confidential information. If you have received it in error, please notify > the sender immediately and delete the original. Any other use of this e-mail > by you is prohibited. > _______________________________________________ > Flashcoders mailing list > [email protected] > http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > _______________________________________________ Flashcoders mailing list [email protected] http://chattyfig.figleaf.com/mailman/listinfo/flashcoders
