DYC = Document Your Code Документировать свой код — прекрасная практика, но все должно быть в меру и к месту. 1⃣ Комментарии в коде — объясняют принятые в коде особенности и допущения реализации 2⃣ Документирующие комментарии — заголовки методов и классов, которые компилируются в документ и парсятся IDE (например, javadoc) 3⃣ Сопроводительная записка (README.md) — файл в корне проекта с описанием проекта и инструкцией по его сборке и запуску 4⃣ Руководство пользователя — отдельный документ или сайт для пользователей приложения. Помните, что программисты, использующие вашу библиотеку, — тоже пользователи. Я выработал для себя следующие практики, которые не меняются уже лет 15: • Самодокументируемый код всегда лучше, хорошему коду не нужны комментарии. • Если мне хочется написать комментарий, я создаю в этом месте вызов нового метода или запись в лог. Текст комментария становится частью кода, в этом и заключается самодокументирование. • Код никогда не врёт, комментарии могут устареть. Чем меньше нужно поддерживать комментарии в коде, тем лучше. • Документирующие комментарии должны отвечать на вопрос "что делает метод или класс", а как он это делает должно быть понятно из кода. • Если в коде пришлось реализовать временный костыль или просто странное и сложное решение, я пишу в коде сопровождающий комментарий. В нем описываю причины такого решения и возможные варианты исправления, пишу TODO. Я пишу его в первую очередь для себя, мне не хочется через полгода заново тратить время на исследования. • Конвенция важнее понятного кода — код должен быть читаемым. Например, если имя метода слишком длинное, его надо либо переименовать, либо разбить на два метода. Если в компании решили, что комментарии и TODO в коде нельзя писать, нахожу для них место в комментариях к задаче или к коммиту. • README.md или его аналог должен обязательно описывать проект и содержать инструкцию по сборке и запуску. Не забывайте прикладывать README.md к решению тестового задания, иначе ваше решение могут вообще не посмотреть. @kodbaza ⚫️ #cleancode #dyc #readme