Ar JavaScript turi komentarų standartą?

Šiuo metu rašau kliento JavaScript kodą ir įdomu, kaip komentuoti savo funkcijas.

Aš atėjau iš C # fono, kur yra oficialiai rekomenduojamas „Microsoft“ dokumentuotas komentarų stilius, kurį aš stebiu, o tai leidžia kompiliatoriui ir kitiems įrankiams automatiškai generuoti dokumentaciją.

Panašiai ir PHP PHPDoc stilius yra visur ir kelyje į oficialų PHP rekomenduojamą standartą .

Ar „JavaScript“ turi bendrą įrankių grandinę, standartą ar geriausią praktiką, kurią galiu taikyti komentuodamas savo funkcijas?

392
12 апр. nustatė mėgėjas balandžio 12 2012-04-12 18:03 '12, 18:03 2012-04-12 18:03
@ 4 atsakymai

Galite naudoti jsdoc stilių, kuris leis jums vėliau sukurti dokumentaciją.

taip

  function sum(a,b) { return a + b; } 

EDIT: Jei naudojate „AngularJS“, galite apsilankyti šiuo adresu: http://google.github.io/styleguide/angularjs-google-style.html

417
12 апр. Atsakymas yra suteiktas nkassis 12 Bal. 2012-04-12 18:06 '12, 18:06 2012-04-12 18:06

Na, yra daug būdų, kaip pridėti komentarus javascript; Čia yra mano rekomendacija .

naudojant // geresnis nei , nes tada galite naudoti paskutinį, kad būtų pašalintas visas blokas su kitais komentarais. Tačiau, jei norite naudoti automatizuotą dokumentų kūrimo įrankį, turite naudoti panašias į javaDoc stiliaus komentarus.

Tai pavyzdys, kuris veiks su YUI DOC (geriausia) http://developer.yahoo.com/yui/yuidoc/#start

border=0
  function SampleFunction (str, obj, callback) { var isTrue = callback(str, obj); // do some process and returns true/false. return isTrue ; } 

Kitos parinktys Pavyzdžiai: - http://usejsdoc.org/tags-param.html

Tikiuosi, kad tai padės jums :)

39
08 сент. Atsakymas, kurį pateikė Vikash Pandey 08 Sep. 2016-09-08 15:48 '16 at 15:48 2016-09-08 15:48

Standartas, kuriuo esu įpratęs, yra JSDoc: https://github.com/jsdoc3/jsdoc

Jis yra panašus į javadoc, jei žinote apie tai.

31
12 апр. Hermo atsakymas, pateiktas balandžio 12 d 2012-04-12 18:06 '12, 18:06 2012-04-12 18:06

Atkreipkite dėmesį į tai, kad pirmiau pateikti atsakymai JSDoc stiliui suteikia jums didelį pranašumą - galite sukurti iš jų dokumentus. Tai ypač vertinga, ypač kai jūsų projektas plečiasi. Jei nesate suinteresuotas JSDoc, ar ieškote bendrų rekomendacijų dėl komentarų, perskaitykite.

Jei jau turite dokumentacijos metodą, kuris tinka jums, laikykitės jo. Jei jums patinka dideli komentarų blokai funkcijų, paaiškinančių viską iš anksto, pradžioje, puikiai. Jei norite įterpti tikslines pastabas konkrečiose eilutėse, naudokite tai.

Kitas dalykas, kurį reikia apsvarstyti, yra kultūra - jei tai yra darbinis projektas, įsitikinkite, kad kodo dokumentacija atitinka jūsų komandos sukurtą dokumentaciją. Taip pat svarbu, kad jūsų kodas atitiktų komandos standartus.

Galutinė mintis turi būti nuosekli. Taisyklių rinkinys, kaip dokumentuoti, net jei tai yra tik jums, padarys jūsų komentarus lengviau skaityti, rašyti ir suprasti vėliau. Jūs žinosite, kur juos ieškoti ir ką jie jums pasakys.

25
12 апр. atsakymas pateiktas „ Surreal Dreams“ balandžio 12 d 2012-04-12 18:05 '12, 18:05 val. 2012-04-12 18:05