Tags:
archive_me1Add my vote for this tag create new tag
, view all tags
Originally posted on PerlTips

  • Today's Poll:
    • Is TWiki code documented adequately for the key developers?
    • Is TWiki code documented adequately for newbies to TWiki?
    • Should it be?
    • If someone were to attempt to add documentation to the TWiki code (with a newbie focus), do you have recommendations about the approach and tools that might be used?
    • If the documentation added were focused on helping newbies, do you have suggestions for keeping that documentation from being a hindrance for more experienced TWiki developer's (while browsing or modifying the code)?

Aside: I recognize that this is probably not a good time to bring up a subject like this, because the key developer's have their hands full, I'm sure, getting ready for the next release. Nevertheless, I wanted to start raising some of these questions for future address.

Aside 2: I've started reviewing some of the TWiki code, and, as a newbie to Perl and TWiki, I feel I've learned quite a bit. I started with the 20010315 beta, and then decided (without finishing that) to download CVS and try to deal with that. I haven't finished, and I'm sort of at a point of diminishing returns -- I don't see much point in continuing the effort if it's just going to create a(n overly) commented copy of an out-of-date TWiki. If anybody's read the LiterateDevelopment page, you'll see some of my related musings over there. (Also, at this point, it would be helpful to have someone look at my poorly formed comments which include questions, and straighten me out when I've gone astray.)

In some cases, I've found variable or function names that don't appear to be very intuitive any more. (I have a feeling they might have been very intuitive at one point in time, but due to modified functionality, the names don't fit the functions as well as they could anymore. When you maintain code and you run into these things, do you consider changing names, adding comments, or ??

-- RandyKramer - 09 Jul 2001

I've not had a problem with variable names. I do think the code could have more comments - by comparison to the codebase for SlashCode, TWiki code has very sparse comments, making it harder than necessary to understand code in some cases. I don't think putting a large quantity of 'newbie focused comments' in the code would be a good idea, but it would be good to see every 'paragraph' of code with a 1-2 line comment, and a slightly longer comment on every subroutine.

Generally, however, the code is quite clean and well-written, from my limited experience with it to date.

-- RichardDonkin - 14 Apr 2002

Topic revision: r1 - 2002-04-14 - RichardDonkin
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.