Sv: Er dokumentasjon relevant for arkiv?

[Thomas Sødring]

Det er interessant Ole. Jeg lurer på hvor mye av *hvem* (altså @author/forfatter) egentlig styres fra git framfor statiske kommentarer i kode.

Noe høres hjemme hos versjonshåndtering (git), noe kan være i kode. Jeg må bare innrømme at jeg har ikke tid til å holde kommentarer oppdatert i nikita (selv om jeg burde). Grunnen til det er tid!

En relevant diskusjon på dette er å finne på SO (https://stackoverflow.com/questions/17269843/javadoc-author-tag-good-practices)

Denne posten (https://stackoverflow.com/questions/3730679/does-source-code-management-make-javadocs-author-and-since-redundant) på har SO også noen gode tanker.

Et annet aspekt med nikita er bruken av @NotNull. Jeg har brukt det for liberalt og har det overalt, mens det egentlig skal kun brukes på interface (definisjon av klasser) og ikke i implementasjonen av klassen. Jeg synes det var greit å se de overalt, men etterhvert opplevde jeg de som støy.

 - Thomas


________________________________
Fra: Ole Aamot <ole at aamotsoftware.no>
Sendt: onsdag 10. august 2022 12:55
Til: Thomas Sødring <tsodring at oslomet.no>
Kopi: nikita-noark at nuug.no <nikita-noark at nuug.no>
Emne: Re: Er dokumentasjon relevant for arkiv?

Boken beskriver javadoc på side 42:

    SUN MICROSYSTEMS recommends the following Javadoc tag ordering:

    In classes and interface descriptions:

    /**
     * Description.
     *
     * @author
     * @version
     *
     * @see
     * @since
     * @deprecated
     */

    Consider including an @author and @version tag in every class or interface description.

    List multiple @author tags in chronological order, with the class or interface creator
    listed first.

    In method descriptions:

    /**
     * Description.
     *
     * @param
     * @return
     * @exception
     *
     * @see
     * @since
     * @deprecated
     */

    Include a @param tag for every parameter.  List multiple @param tags in parameter declaration order.

    Include a @return tag if the method returns any type other than void.

    Include an @exception tag for every checked exception listed in a throws clause.
    Include an @exception tag for every unchecked exception that a user may reasonably expect to catch.
    List multiple @exception tags in alphabetical order of the exception class names.

Mvh,
Ole

> On Aug 9, 2022, at 11:16 AM, Thomas Sødring via nikita-noark <nikita-noark at nuug.no> wrote:
>
> Godt spørsmål Ole! Dokumentasjon finnes på mange måter.
>
> nikita skal støtte swagger/openapi beskrivelser. Feks det ser du i controller:
>
> https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgitlab.com%2FOsloMet-ABI%2Fnikita-noark5-core%2F-%2Fblob%2Fmaster%2Fsrc%2Fmain%2Fjava%2Fnikita%2Fwebapp%2Fweb%2Fcontroller%2Fhateoas%2FFondsHateoasController.java%23L45&data=05%7C01%7Ctsodring%40oslomet.no%7C794d3b342c344ac591d208da7abeca47%7Cfec81f12628645508911f446fcdafa1f%7C0%7C0%7C637957257106185290%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=q7Yuy%2BWvnJX0Tp%2BO8BXBNf%2FhYx4oCMw0Q3RijjXHa2Q%3D&reserved=0
>
> Det er mulig å starte nikita sammen med swagger-api beskrivelse. Men jeg har ikke løst samhandlings biten at du faktisk kan POSTE/PUT fra swagger.
>
> Det er noe javadoc dokumentasjon. Feks
>
> https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgitlab.com%2FOsloMet-ABI%2Fnikita-noark5-core%2F-%2Fblob%2Fmaster%2Fsrc%2Fmain%2Fjava%2Fnikita%2Fwebapp%2Fservice%2Fimpl%2FFondsService.java%23L83&data=05%7C01%7Ctsodring%40oslomet.no%7C794d3b342c344ac591d208da7abeca47%7Cfec81f12628645508911f446fcdafa1f%7C0%7C0%7C637957257106341516%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=J5ZTAl9iY3xRsB3gsBxdXL%2FyCV70tJ2o%2FWz8ONW8UgQ%3D&reserved=0
>
> men dette er også noe som burde blitt gjennomgått i mer detalj.
>
> Nikita har integrert spring-restdocs-asciidoctor og når tester kjøres genereres det en https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fasciidoctor.org%2Fdocs%2F&data=05%7C01%7Ctsodring%40oslomet.no%7C794d3b342c344ac591d208da7abeca47%7Cfec81f12628645508911f446fcdafa1f%7C0%7C0%7C637957257106341516%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=78U075ciMDTn%2BSK%2B89tVHoX4SDzLMIhFf3O%2BniHlgvc%3D&reserved=0 fil
>
> Vi har desverre ikke hatt tid til å ta tak i dette og strømlinje det.
>
>  - Thomas
>
> Fra: nikita-noark <nikita-noark-bounces at nuug.no> på vegne av ole at aamot.software <ole at aamot.software>
> Sendt: tirsdag 9. august 2022 11:05
> Til: Petter Reinholdtsen <pere at hungry.com>
> Kopi: nikita-noark at nuug.no <nikita-noark at nuug.no>
> Emne: Re: Er dokumentasjon relevant for arkiv?
>
> On Aug 9, 2022 9:48 AM, Petter Reinholdtsen <pere at hungry.com> wrote:
> [Thomas Sødring]
> > Ble tilsendt følgende lenke fra en kollega på arkivstudiet:
> >
> >  https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kode24.no%2Fartikkel%2Frolfs-beste-tips-for-god-dokumentasjon-i-dag-er-dette-ekstremt-viktig%2F76736767&data=05%7C01%7Ctsodring%40oslomet.no%7C794d3b342c344ac591d208da7abeca47%7Cfec81f12628645508911f446fcdafa1f%7C0%7C0%7C637957257106341516%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=vun4Yn62D1lPqPqgPJ1mFehEIVQ0LpRh4JpJpndjR0o%3D&reserved=0
> Takk for den.  En nyttig påminning og et godt mentalt rammeverk for å
> vurdere dokumentasjonsbehovet.
> Og javadoc benyttes naturligvis i Nikita?
>
> Jeg fant en bok med tittelen
>
> The Elements of Java Style
>
> hvor javadoc er beskrevet på side 42.
>
> Mvh,
> Ole
>
> _______________________________________________
> nikita-noark mailing list
> nikita-noark at nuug.no
> https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.nuug.no%2Fmailman%2Flistinfo%2Fnikita-noark&data=05%7C01%7Ctsodring%40oslomet.no%7C794d3b342c344ac591d208da7abeca47%7Cfec81f12628645508911f446fcdafa1f%7C0%7C0%7C637957257106341516%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=RKWKIBewKofdslXvlgWcqH6Us1HVZblnGhba%2BLyHGcI%3D&reserved=0
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.nuug.no/pipermail/nikita-noark/attachments/20220810/a6c00339/attachment-0001.htm>