Када размишљате о програмирању, природно је да се фокусирате на теме као што су језици, алгоритми и отклањање грешака. Али техничка документација може бити једнако важна да се исправи.

Без добре документације, поновна употреба кода може патити. Корисници који су нови у бази кодова могу се лако изгубити или фрустрирати ако документација није до нуле. Није само важно разумети шта програм ради, већ и како – или чак зашто – то ради.

Пакети као што су Пидоц за Питхон и Јавадоц за Јава помажу аутоматизацијом дела процеса. Алат Годоц ради исто за Го.

Шта је Годоц?

Годоц је Го пакет који вам омогућава да креирате, управљате и користите Го документацију на „Тхе Го ваи“. Го начин је скуп принципа које, као Го програмер, треба да следите да бисте побољшали квалитет кода.

Користећи Годоц, можете лако читати документацију и код других програмера. Такође можете аутоматизовати креирање сопствене документације и објавити је користећи Годоц.

Годоц је сличан Јавадоц, документатор кода за Јаву. Обојица користе коментаре и код у модулима за генерисање документације. И оба алата структурирају ту документацију у ХТМЛ-у тако да можете да је видите у прегледачу.

Почетак рада са Годоцом

Коришћење Годоца је једноставно. За почетак, инсталирајте Годоц пакет са веб локације голанг користећи ову команду:

иди набавите голанг.орг/к/тоолс/цмд/годоц

Покретање ове команде ће инсталирати Годоц у ваш наведени радни простор. Када се заврши, требало би да будете у могућности да покренете годоц команду у терминалу. Ако има грешака у вашој инсталацији, покушајте да ажурирате Го на најновију верзију.

Годоц тражи коментаре у једном и више редова које ће укључити у документацију коју генерише.

Обавезно форматирајте код на начин Го, као што је објашњено у публикација Еффецтиве Го од стране Го тима за најбоље резултате.

Ево примера коришћења коментара у једном реду у стилу Ц++:

// Корисник је модел структуре који садржи
тип Корисник струцт {
}

Такође можете користити блок коментаре у стилу Ц:

/* 
Корисник је прилагођена структура података
Овде можете укључити било који текст и Годоц сервер ће га форматирати када га покренете.
*/
тип Корисник струцт {
}

У горњим коментарима, „Корисник“ почиње реченице јер коментар описује шта структура корисника ради. Ово је једна од многих тема о којима говори Го ваи. Покретање реченица документације са корисним именом је кључно јер се прва реченица појављује на листи пакета.

Покретање Годоц сервера

Када коментаришете свој код, можете покренути годоц команду у вашем терминалу, из директоријума кода вашег пројекта.

Конвенционално, Го програмери користе порт 6060 да угости документацију. Ово је команда за покретање Годоц сервера на том порту:

годоц -хттп=:6060

Горња команда хостује документацију вашег кода лоцалхост, или 127.0.0.1. Порт не мора да буде 6060; годоц ће радити на било којој незаузетој луци. Међутим, увек је најбоље следити конвенције Го документације.

Када покренете команду, своју документацију можете погледати у претраживачу тако што ћете посетити локални хост: 6060. Време које је Годоцу потребно за генерисање ваше документације зависиће од њене величине и сложености.

Код испод се придржава Го ваи, у овом случају користећи коментаре у једном реду.

// назив пакета
пакет корисник
// фмт је одговоран за форматирање
увоз (
 "фмт"
)


// Корисник је структура људских података
тип Корисник струцт {
 Старост инт
 Име низ
}


фунцглавни() {
// хуман је иницијализација структуре Усер
 човек := Корисник {
 Старост: 0,
 Име: "особа",
 }


фмт. Принтлн (људски. разговор())
}
// Талк је метод структуре Усер
фунц(корисник примаоца)Причај()низ {
повратак „Сваки корисник може нешто да каже!“
}

Ако покренете Годоц на модулу кода изнад, требало би да видите излаз који изгледа отприлике овако:

Имајте на уму да је у познатом формату, сличном ономе што ћете наћи на Го званичној веб страници документације.

Годоц користи коментар који претходи декларацији пакета као Преглед. Уверите се да овај коментар описује шта ваш програм ради.

Тхе Индекс садржи везе ка декларацијама типа и методама тако да можете брзо доћи до њих.

Годоц такође пружа функционалност за преглед изворног кода који чини пакет у Фајлови пакета одељак.

Побољшање ваше документације помоћу Годоц-а

Можете укључити више од обичног текста у своју Годоц документацију. Можете додати УРЛ-ове за које ће Годоц генерисати везе и структурирати ваше коментаре у параграфе.

Ако желите да се повежете са ресурсом, упишите УРЛ у свој коментар и Годоц ће га препознати и додати везу. За параграфе оставите празан ред за коментаре.

// Пакет главни
пакет главни
// Документ представља обичан документ.
//
// Линк за https://google.com
тип Документ струцт {
 странице инт
 референце низ
 потписан боол
}


// Врите уписује нови документ у складиште
//
// Можете научити о писању са Википедиа.цом
фунцПишите() {
}

Имајте на уму да Годоц захтева да напишете УРЛ адресе у потпуности да би их повезао. У овом примеру, Гоогле УРЛ адреса укључује хттпс:// префикса, тако да Годоц додаје везу на њега. Пошто домен Википедије није сам по себи пун УРЛ, Годок ће га оставити на миру.

Ево неколико најбољих принципа које треба применити када документујете свој Го код:

  • Нека ваша документација буде једноставна и сажета.
  • Почните реченицу функција, типова и декларација променљивих њиховим именима.
  • Започните ред са увлачењем да бисте га унапред форматирали као код.
  • Коментари који почињу „БУГ(име)“ попут „БУГ(јое): Ово не ради“ су посебни. Годоц ће их препознати као грешке и пријавити их у сопственом делу документације.

Годоц вам може олакшати проблеме са документацијом

Користећи Годоц, можете бити продуктивнији и мање бринути о напорима да документујете своје програме ручно.

Требало би да ваша документација буде прецизна, детаљна и тачна како бисте је циљној публици лакше прочитали и разумели. Такође је од виталног значаја да ажурирате коментаре кода док мењате свој програм.

Погледајте документацију Годоц пакета да бисте сазнали више о коришћењу Годоц-а.