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 > >Flashcoders@chattyfig.figleaf.com > >http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > > _______________________________________________ > Flashcoders mailing list > Flashcoders@chattyfig.figleaf.com > http://chattyfig.figleaf.com/mailman/listinfo/flashcoders > _______________________________________________ Flashcoders mailing list Flashcoders@chattyfig.figleaf.com http://chattyfig.figleaf.com/mailman/listinfo/flashcoders
