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

 /** Функция для получения покупателей **/. 

Ну вот правда - это просто лишняя строка кода, прочитав его я не получу ни какой новой инфы о том что делает функция getCustomer(), то что она получает покупателя я и так вижу из названия. Откуда она его получает, для чего, какие конкретно данные о покупателе она получает, не понятно (тут не будем останавливаться на том что тип возвращаемого значения можно указывать, в данном случае это лишнее).

Почему бы для этой функции не написать вот такой комментарий

/** Получает строку с данными покупателя из таблицы customers **/

На мой взгляд этот комментарий не на много длиннее, но значительно информативнее. Прочитав его я могу понять что мне ждать в ответе. Это либо null, либо строка из таблицы customers.

Так же при оформлении комментариев хорошей практикой является придерживание определенных стандартов. Для каждого языка они свои, но в целом очень похожи. Например для PHP - это PHPDoc. Многие редакторы также понимают синтаксис стандартных комментариев PHPDoc.

Как не правильно документировать код.
1. Написать MVP.
2. Получить обратную связь и правки.
3. Внести правки, отрефакторить код.
4. Написать комментарии.

Как правильно документировать код.
1. Начать писать писать комментарии к функциям на этапе начала разработки. То есть написал функцию и сразу задокументировал ее. Ок все правильно сделал.
2. После того как свеженькая функция задокументирована сразу можно начать ее править, естественно уже написанные комментарии при этом менять не нужно, ну или максимум поменять только при первой правке, больше смысла не имеет.
3. Понять что написанная функция не нужна в принцыпе и удалить ее.
4. Нет все таки нужна! Написать заново, но наученный прошлым опытом решить задокументировать потом.
5. Дописать первую версию фичи, попытаться задокументировать то что было пропущено в процессе разработки.
6. Получить порцию правок, начать внедрять их не обращая внимания на комментарии.
7. Попробовать выпустить релиз.
8. Понять что все работает не так, в панике править имеющийся код и дописывать новые функции не обращая внимание на комментарии.
9. Тешить себя мыслью, что будет время для рефакторинга.
10. Начать разработку новой фичи.

Прогресс ради прогресса
#личноемнение

1. Фейковое развитие 🏗🏕
====================================================
Задумался тут вот о такой штуке как развитие веба. Безусловно он сейчас, как говориться, шагнул очень далеко, и получил широкое развитие. Но вот только на мой взгляд он идет по экстенсивному пути. То есть несмотря на то что все разработчики, все издания, гайды, приложения и т.д. пишут о необходимости минимизации трафика, оптимизации использования ресурсов, сжатии и обфускации кода, оптимизации картинок и много еще всего такого. Вот несмотря на все это по факту мы ничего не оптимизируем, а тупо увеличиваем мощности, расширяем каналы трафика, увеличиваем скорости интернета, увеличиваем объемы памяти. Все это конечно здорово что интернет становится быстрее, и компы становятся все мощнее, но из за того что в разработке мы только лишь говорим об оптимизации, но по большому счету ей не занимаемся, мы не видим существенного улучшения от этого.

2. Пруфы ⚙️📺
====================================================
Приведу небольшой пример который немного визуализирует то что хотел сказать. 10 лет назад я мог без труда зайти на ютубчик и смотреть на нем любимые видосики я могу сделать это и сейчас, собственно ни чего не изменилось все как и 10 лет назад. Но есть одно отличие 10 лет назад я делал это на компе у которого было внимание 512 MB оперативы. Да и по тем меркам это был хлам, но тем не менее видосики на нем я смотрел без особых проблем. Скажу больше, я на нем не только их смотрел но и монтировал и рендерил. На моем нынешнем ноуте имеется 8 GB оперативной памяти, что в 16 раз больше. При сравнении кажется как это дофига, но хотя давайте взглянем. Просто два открытых поисковика в хроме сейчас занимают 400 мегабайт моей оперативы, на что! что блин на главной странице Яндекса и Гугла такого что может весить 400 мгабайт (ну ладно, если быть честными до конца сами страницы весят по 80 и 40 метров, остальное это движок хрома, но все равно я блин просто открыл браузер и лишился 400 мегабайт). Ок давайте посмотрим какой нибудь видосик. Что правда? 570 мегабайт для трех вкладок? Ок на своем старом компе посмотреть это видео нормально мне уже не удастся. Да и на современном если я активно работаю, например у меня открыт пхпшторм, пару вкладок в браузере и в другом браузере фоном играет музыка, я уже испытываю затруднения. Про рендеринг видео говорить не приходится. То есть по сути что раньше что сейчас я могу выполнять одни и те же задачи причем с одинаковой загрузкой компьютера.

3. Сейчас научу как надо 😂📚
====================================================
Что-ж это не радует даже несмотря на лучшее качество видео и прочие и т.д. Все таки хотелось бы чтобы по мере прогресса одни и те же задачи становились легче и занимали относительно меньше ресурсов. Что я хочу сказать - если 10 лет назад на среднем компе я мог монтировать видео среднего для того времени качества, то сейчас на среднем компе я хочу монтировать 2 видео среднего для настоящего времени качества. Это называется интенсивный рост, то есть качественный. Это прогресс здорового человека а не просто тупое увеличение мощностей.
Немного утрированная мысль конечно но все же думаю имеет под собой определенное здравое зерно.

Многие новички не уделяют должного времени на изучение GIT перед тем как начать свою карьеру в разработке. Из-за этого приступив к командной разработки, они могут доставить много головной боли и себе и всей команде. Начиная с попадания в коммиты каких-то левых файлов и заканчивая затиранием измененией своих коллег. Ох как это доставляет, когда смотришь коммит джуна и спрашиваешь - "а зачем ты удалил какую то функцию из ядра проекта?". Ответ - "я там ни чего не трогал". Ну классика же). Или когда кто то путается в своих же фичах и бранчах и теряет изменения. Ну это ли не веселье - всей командой отыскивать и восстанавливать его изменения. Это не для обиды написано или чтобы над кем то посмеяться, а для того чтобы обратить внимание на такой важнейший инструмент как GIT.

Приведу буквально 5 команд которые вы должны знать на отлично, чтобы избежать этих проблем.

1. Клонирование репозитория. Понимать разницу между работой с репозиторием по https и ssh. Уметь настроить доступ по ssh. Команда git clone

2. Создание, удаление, переключение между ветками. Особое внимание тут нужно уделить пониманию как ведут себя ваши не закомиченные изменения при переключении между ветками и создании новых веток. git branch, git branch -d, git checkout

3. Понимание разницы между локальной и удаленной веткой. Синхронизация с удаленной веткой. Подтянуть, запушить изменения. git pull , git push

4. Понимание состояний изменений. Незакомичено, добавлено в индекс, закомичено. Умение их отменить и добавить. git commit, git checkout, git add, git reset

5. Переключение между между коммитами, понимать что такое HEAD git checkout

6. Это уже в виде факультатива, не раз видел как разрабы проработавшие больше года не могли сменит адрес или имя ссылки на удаленный репозиторий. git remote -v git remote add git remote get-url

Если вы будете кристально прозрачно понимать эти концепции - цены вам не будет на начальных этапах. Удачи!