Komentowanie czegoś jest w zasadzie sposobem, w jaki ktoś może ocenić lub przedstawić coś z innej perspektywy, niezależnie od tego, czy jest to dobre , czy złe w procesie, zastanowimy się, czy poprawimy się na podstawie tego, czy po prostu zignorujemy, zgodnie z komentarzami to nam dane.

Ale w tym poście nie będziemy rozmawiać o polityce, ale o bardziej technicznych kwestiach związanych z tworzeniem stron internetowych, a moim zdaniem musimy to robić podczas pisania naszego kodu.

W naszej dyskusji tym razem przekonamy się, jak ważne jest komentowanie funkcji, którą sami stworzyliśmy, oczywiście w JavaScript. Wyobraź sobie, że mamy taką funkcję:

function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

window.location.href = `${x}://${y}`;

Co to jest wyjaśnienie argumentów `x`i `y`? czy wypełnimy, `object`czy `string`może możemy uzupełnić jakiś specjalny wpis? inny używamy TypeScript, mechanizm danych typu zostanie wykonany przez sam TypeScript w czasie wykonywania lub może w fazie programowania , ale może użyjemy JavaScript?

Tak, w JavaScript (JS) argumenty w `setLocation`funkcji będą wyświetlane przez edytor IntelliSense jako `any`oznaczające, że jakiekolwiek dane będą dozwolone.

Jak widać w zasadzie, jest tu problem dwojga; Komputer i człowiek , gdy komputer odczyta kod, będzie działał bez względu na ustawioną nazwę argumentu, ale co z człowiekiem ?

Funkcja, którą stworzymy, będzie trudna do zrozumienia dla następnego programisty (Człowieka), ponieważ nie wiedząc, co wysłać do `setLocation`funkcji, jest inaczej, jeśli zostawimy komentarz

// args `x` with data type string, is a protocol
// args `y` with data type string, is a domain name
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Postaramy się skomentować stworzoną przez nas funkcję, zgodnie ze standardem JSDoc , zmienimy powyższy komentarz na coś takiego

/**
 * A function that can be executed on address bar browser
 * @param {string} x a host url
 * @param {string} y a domain url
 */
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Rzeczywiście, IntelliSense może po prostu pomóc użytkownikom określić, co powinno zostać wysłane w tej funkcji, kiedy chcemy tego użyć, ale nie jest to całkowicie wpisane ściśle

Jest to bardzo pomocne, zwłaszcza jeśli mamy funkcję, w której powinniśmy wysłać obiekt danych jako parametr funkcji, na przykład mamy taką funkcję

/**
 * @param {object} fullName
 * @param {string} fullName.firstName your first name
 * @param {string} fullName.lastName your last name
 */
function overwriteData(fullName) {
  return {
    firstName: "Adib",
    lastName: "Firman",
    ...fullName
  };
}

Jak zwykle IntelliSense da nam podpowiedź, a wiadomo, że tym bardziej interesujące jest takie podejście

Na powyższym obrazku będziemy wprowadzać dane zgodnie z instrukcją IntelliSense oczywiście dostaniemy podpowiedź od naszego redaktora, ciekawe prawda?

Kolejne pytanie brzmi: czy powinniśmy komentować wszystkie stworzone przez nas funkcje? Oczywiście, że nie, przykład takiej funkcji

const sum = (firstNum, secondNum) => firstNum + secondNum;

Wniosek

Skomentuj naszą funkcję, w zależności od tego, jak będzie używana, czy podane parametry są bardzo złożone ? czy też można go odczytać z funkcji nazewnictwa i utworzonych argumentów ?

Ale jeśli uważasz, że funkcja wymaga komentarza, to lepiej, bo ma to ułatwić utrzymanie jej przez kolejnego programistę (Human).

Dziękuję Ci.