Správně komentovaný kód. Doslovné versus kontextové komentáře

Proces v 5 krocích, kterým by měl váš kód projít

1. Náčrt kódu: Chápete problém a jak jej vyřešit pomocí kódu. Rychle to vypište, neztrácejte čas přemýšlením o jménech, soustřeďte se jen na logiku.

let x = $(thing).height();
if (x < 248) {
  $(otherThingy).css('width', 300);
}

2. Doslovný Komentáře: Napište komentář vysvětlující, co váš kód doslova dělá na každém řádku

// Get the height of the sidebar
let x = $(thing).height();
// If the sidebar height is less than 248px
if (x < 248) {
  // Set the navigation in the sidebar to be 300px wide
  $(otherThingy).css('width', 300);
}

3. Refaktor: Použijte jazyk, který jste napsali ve svých komentářích, aby byl kód snadněji čitelný a nahradil všechny komentáře.

let sidebarHeight = $('.sidebar').height();
if (sidebarHeight < 248) {
  $('.sidebar nav').css('width', 300);
}
  • A tady můžete přestat. To je přijatelné kód. Je to lepší než předtím, a jakmile to několikrát uděláte, můžete přeskočit krok 2 a někdy přeskočit krok 1, pokud už máte pro tyto věci v hlavě jména, a přejít rovnou ke kroku 3. Každý by měl a bude dostat se do tohoto bodu po nějaké praxi. Komentování každého řádku je proto dobré cvičení. Tyto tři kroky nakonec vždy udělá každý, i když jen mentálně. Ale umíme to lépe. Pokračujme.

4. Kontextové Komentáře: Přidejte zpět komentáře, tentokrát s vysvětlením důvodu za tímto kódem existujícím.

// We need to get the sidebar height because the UI relies on a 3rd party
// xyz module for our advertising that takes up height in the sidebar
let sidebarHeight = $('.sidebar').height();
// We specifically check this height because it's based on the default
// size of the advertising iframe from xyz. 248 is unique to xyz.
if (sidebarHeight < 248) {
  // Because of xyz's requirements the nav needs to be between 280 & 345
  $('.sidebar nav').css('width', 300);
}

5. Refaktorové komentáře: Vložte kontextové komentáře do kódu pomocí nových názvů proměnných nebo funkcí

function setSidebarWidthBasedOnXyzIframe () {
  let sidebarHeight = $('.sidebar').height();
  let defaultXyzAdvertisingIframeHeight = 248;
  if (sidebarHeight < defaultXyzAdvertisingIframeHeight) {
    // must be between 280 & 345
    let xyzNavWidth = 300;
    $('.sidebar nav').css('width', xyzNavWidth);
  }
}
setSidebarWidthBasedOnXyzIframe();

Vidíte, tyto komentáře mi hodně říkají .

  • Vím, že 248 je specifický a nedotýkat se ho.
  • Vím, že 300 může to být řada čísel a jaké to jsou pro případ, že to budu muset v budoucnu aktualizovat. Nebudu muset tyto informace znovu objevovat.
  • A hlavně vím, že naše společnost nepoužila XYZ Advertising po dobu 2 let a že veškerý tento kód lze odstranit !

Žádná z těchto informací není sdělena, pokud se zastavíte v kroku 3. Nevím, jakou váhu mají použitá čísla. Co je/není bezpečné změnit. Neznám důvod proč bylo vytvořeno pro začátek.

Možná můžete některé z těchto informací předat zabalením do funkce nebo pojmenováním souboru. Ale to by mělo být určeno stylem kódu a architekturou projektu, ne proto, že se chcete vyhnout psaní komentářů. Pokud architektura vašeho projektu umožňuje nebo podporuje tento styl kódování a můžete předat informace v názvu souboru nebo něco podobného, ​​je to v pořádku, jde o to, že kontextové informace musí být někam předány ve vztahu k samotnému kódu.

Souhrn

Existují dva typy komentářů, doslovné komentáře, které říkají, co něco je a kontextové komentáře, které vysvětlují proč něco je.

Doslovný komentář je dobrý pro lepší pojmenování proměnných/funkcí a měl by být k tomu použit a poté zahozen.

Kontextový komentář poskytuje kontext vašemu kódu a poskytuje metadata, která budou užitečná pro ty, kteří si tento kód prohlížejí poprvé. Tyto by měly být použity, kdykoli je to možné. Pokud existují doplňující informace, které nejsou uvedeny, měly by být zdokumentovány s kódem v kontextu.

Všechny řádky vyžadují doslovné komentáře, i když jsou před vyřazením napsány pouze v duchu.

Ne všechny řádky vyžadují kontextové komentáře. Ale kdykoli mohou mít je, musí . Jinak děláte medvědí službu sobě i těm, kteří přijdou po vás.

Fotografie:Teo Duldulao, Roman Serdyuk