(Self) Documenting Code

🇭🇷 Svi cijene dobro napisanu dokumentaciju. Ipak, kad se radi o vlastitim projektima, često dajemo prednost brzini i potpuno preskočimo dokumentaciju. Nemamo vremena čitati, a kamoli pisati stranice teksta. No, kad se nađemo pred zadatkom razumijevanja koda koji je napisao kolega — ili čak mi sami u prošlosti — shvatimo koliko nam zapravo nedostaju objašnjenja.

U ovom predavanju istražit ćemo što zapravo znači softverska dokumentacija, koje sve formate može imati i kako odabrati pravi pristup dokumentiranju za različite vrste projekata. Također ćemo raspraviti tehnike pisanja samodokumentirajućeg koda koje olakšavaju razumijevanje budućim čitateljima, smanjujući potrebu za formalnom dokumentacijom bez gubitka jasnoće.

🇬🇧 Everyone appreciates well-written documentation. Yet, when it comes to our own projects, we often prioritize speed, and skip the documentation altogether. We don’t have the time to read, let alone write, pages of text. However, when we’re faced with understanding code written by a colleague—or even our past selves—we find ourselves longing for explanations.

In this talk, we’ll explore what software documentation really is, the various formats it can take, and how to choose the right documentation approach for different types of projects. We’ll also discuss techniques for writing self-documenting code that enhances understanding for future readers, minimizing the need for formal documentation without compromising clarity.

📣 Speaker: Ines Jelovac Mandarić

©️ Cover image by vectorjuice / Freepik.