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
