By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
459,466 Members | 1,130 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 459,466 IT Pros & Developers. It's quick & easy.

Proper Script/Code Documentation

P: n/a

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.

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.

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.

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?

Aug 25 '08 #1
Share this Question
Share on Google+
2 Replies


P: n/a
On Mon, 25 Aug 2008 at 11:46:32, in comp.lang.javascript, Patient Guy
wrote:
>
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.

>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.

>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.

>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
Aug 25 '08 #2

P: n/a
On 25 Aug., 18:46, Patient Guy <sevisen.adam@gmailDOTHEREcomwrote:
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.
Check out JsDoc Toolkit (http://jsdoctoolkit.org/). You can comment
your sources using the JsDoc syntax (it's like Javadoc) and than
generate documentation running JsDoc Toolkit from commandline.

Regards,
purcaholic
Aug 25 '08 #3

This discussion thread is closed

Replies have been disabled for this discussion.