Jeden z najnudniejszych, najmniej seksownych, najczęściej odsuwanych w czasie tematów w projektach? Dokumentacja! W tym odcinku rozmawiamy właśnie o niej…

Tworząc projekt open source w pewnym momencie przychodzi czas, w którym należałoby nasze dzieło udokumentować celem jego zrozumienia przez innych programsitów. Dostawcy usług jak GitHub czy Bitbucket oferują wbudowane mechnizmy jak popularne Wiki, jednak według mnie posiadają one kilka zasadniczych minusów:Wiki jest nierozłączną częscią repozytorium projektu (choć można zrobić niezależny clone).Wiki nie jest (jawnie) wersjonowane. Wgląd w kolejne rewizje jest możliwy, ale nie mamy mozliwości np. utworzen...

Programiści z dokumentacją mają taki problem, że nie lubimy jej czytać i nie lubimy jej pisać. Niestety często wiąże się to z ciekawymi WTFami gdy kod zachowuje się nie tak jakbyśmy tego od niego oczekiwali.

Writing a project documentation – everyone’s or at least the programmer’s nightmare, right? Although at a first glance many of you will most likely agree with the given assumption, I’ll try to convince you otherwise. Not only it doesn’t have to be a dull experience, but it might be a truly fun and quite refreshing activity, which shall provide the great value for the project.

C# ma tę genialną zaletę, że pozwala komentować swoją treść specjalnymi znacznikami XML. Natychmiastowym efektem takich komentarzy jest ich prezentacja w postaci pomocy kontekstowej dla elementów kodu, które zostały nimi opatrzone. Drugie ich zastosowanie, to możliwość wygenerowania dla każdego pliku z treścią oprogramowania dokumentacji zawierającej elementy opatrzone wspomnianym typem komentarza. Niestety – określanie tych plików mianem dokumentacji jest nadużyciem...