История изменений

Начни с чтения книжек Совершенный Код (Code Complete, Макконнелл) и Рефакторинг (Фаулер). Есть, например, на рутрекере.

нужно ли по шагам описывать алгоритм

когда пишешь функцию, сразу называешь ее не ABC, а нормально. Если те, кто будут пользоваться твоей функцией, предположительно идиоты - можно писать сколько угодно длинное название функции, лишь бы было с первого взгляда понятно, что она делает. То же про названия переменных. Код сам должен говорить за себя.

дальше, пока еще пустое тело функции наполняешь комментариями на человеческом языке. Просто последовательность действий, которую нужно совершить, как в списке дел на сегодя.

по ходу кодинга, заменяешь комментарии реальным кодом. Или не заменяешь, а просто подписываешь код ниже уже готовых комментариев. В результате у тебя получаются И комментарии (отражающие самую суть) И код. Потом уточняешь мелкими комментариями сложные места. Последнее действие - написание заголовка автодокументации для функции.

это (и другое) есть в литературе по TDD и BDD. Например, «Экстремальное программирование: разработка через тестирование» Кента Бека (есть на рутрекере)

«Склеивает три символа и отдает строкой»

это ОК, более точные параметры люди сами посмотрят по сигнатуре функции. В документации нужно отразить самую суть. В излишних подробностях суть исчезает (кроме того, начинается серьезное дублирование между кодом и комментарием).

Начни с чтения книжек Совершенный Код (Code Complete, Макконнелл) и Рефакторинг (Фаулер). Есть, например, на рутрекере.

нужно ли по шагам описывать алгоритм

когда пишешь функцию, сразу называешь ее не ABC, а нормально. Если те, кто будут пользоваться твоей функцией, предположительно идиоты - можно писать сколько угодно длинное название функции, лишь бы было с первого взгляда понятно, что она делает. То же про названия переменных. Код сам должен говорить за себя.

дальше, пока еще пустое тело функции наполняешь комментариями на человеческом языке. Просто последовательность действий, которую нужно совершить, как в списке дел на сегодя.

по ходу кодинга, заменяешь комментарии реальным кодом. Или не заменяешь, а просто подписываешь код ниже уже готовых комментариев. В результате у тебя получаются И комментарии (отражающие самую суть) И код. Потом уточняешь мелкими комментариями сложные места. Последнее действие - написание заголовка автодокументации для функции.

«Склеивает три символа и отдает строкой»

это ОК, более точные параметры люди сами посмотрят по сигнатуре функции. В документации нужно отразить самую суть. В излишних подробностях суть исчезает (кроме того, начинается серьезное дублирование между кодом и комментарием).