Как да обучим разработчиците да документират вашия код, статия
Кодът лошо ли е документиран? Вероятно проблемът не е в програмистите, а в това как е структурирана работата в компанията.
Доста е трудно да намерите и привлечете висококачествени разработчици във вашия екип. Но придобиването на служители, които са добри в документирането на кода, на пръв поглед не е проблем.
Нека се абстрахираме от потребителската документация засега. Ръководствата, справочните ръководства и онлайн документацията са текстове, които най-добре се оставят на техническите автори. В крайна сметка специализацията на техническите спецификации е да се представят техническите спецификации на достъпен език. Такава документация вече е написана за крайния продукт. В процеса на разработване на програма обаче е много важно да се поддържа подробна документация за вътрешна употреба.
Защо програмистите не документират код, колко документация е необходима и как най-добре да се направи
Винаги има оборот в екипа за разработки - това е нормално в бизнеса. Програмист може да смени работата, да се премести от един отдел в друг или дори да напусне ИТ сферата като цяло. Не са изключени и доста мрачни обрати - сериозно заболяване, увреждане или смърт. Всички тези фактори могат драстично да ограничат способностите на отбора в най-неподходящия момент. Кодът също остарява; програмист може да забрави как работи неговият собствен код, ако не се е справял с него от една година или повече.
Защо програмистите не пишат документация?
Има много причини, поради които разработчиците не документират своя код. Някои са по-лесни за поправяне от други.
Това отношение към работата е разрушително и неприемливо. Но примери за такъв непрофесионализъм са по-рядко срещани, отколкото може да изглежда. В по-голямата част от случаите разработчиците не документират код по много по-прозаични причини.
Първо, кога точно трябва да документира код на програмист? Добре известно е, че софтуерните модули често се пишат и след това се пренаписват много пъти преди пускането, но те могат да бъдат добавени по-късно. Ако разработчик започне да документира внедряването на API твърде рано, все едно се абонира за дизайнерски решения, които са само хипотетични. Освен това, ако по-късно спецификацията или изискванията се променят, но никой не помни, че ръководството също трябва да бъде пренаписано, тогава ще се появи неточна и остаряла документация. Този резултат е дори по-лош от пълното й отсъствие. Тези проблеми се влошават само в контекста на съвременните гъвкави програмни методологии, където акцентът е върху свръхбързото генериране на код и итеративното разработване.
Друг въпрос - колко време трябва да отдели програмист за писане на документация? В повечето компании основните отговорности на разработчика са да проектира, внедри, отстрани грешки и поддържа кода. Но ако изпълнението на програмиста се оценява главно чрез изпълнението на тези основни задачи, той е по-вероятно да свърши останалата (по-малко съществена) работа последно, особено ако организацията обръща твърде много внимание на стандартите за изпълнение, които идват от тавана. Най-вероятно документирането на кода ще се възприеме като "тривиална работа".