On Mon, 25 Aug 2008 at 11:46:32, in comp.lang.javascript, Patient Guy
wrote:
Quote:
>
>I am looking for standards or advice or guidelines, either written in a
>posted reply here or given by a link in your reply, that gives CONVENTIONAL
>or TRADITIONAL or ACCEPTED-STANDARD formatting for how to document
>script/code. My guess is also that this is used by automatic
>documentation-gathering software tools.
If you're using software tools you won't have much choice. You'll just
have to learn to live with whichever format rules you don't like.
Quote:
>I have a fair idea that classes/functions should be described at a minimum
>as to purpose, parameters passed, and return value(s). But there is a lot
>of other symbols/characters used, including how "to version" the code.
Keep it simple, keep it clear, don't neglect it, and, above all, keep it
up to date. That last one is easier if you've kept it simple and clear.
Quote:
>With descriptions (with multiple paragraphs similar to UNIX documentation),
>I tend to put them at the bottom of a *.js file between /* */ delimiters,
>with a line at the top directing the reader to the bottom of the script
>file.
Surely the best two choices are to put a function's specification inside
the function or in a separate document. Anywhere else will be more
trouble to read, write, and update.
Quote:
>What are everyone's (best?) practices here?
>
>How do you avoid the problem of coming back to YOUR OWN code months later
>and trying to figure out what you were doing, let alone having another
>developer come to your code and instantly picking up the ball and running
>with it?
This works for me :
function Vet(form)
// Vet the form and return true iff values are ok
{ ... }
And so does this :
function DayName(dow)
// Return name for day of week dow (English)
// In and Pre
// dow : Integer
// Out and Post
// DayName : String
// DayName is name of day dow if 0 <= dow <= 6
// DayName is "<unknown>" otherwise
{ ... }
John
--
John Harris
