Как делать комментарии в коде только для себя?

Question

[mkone112]

Как можно писать комментарии в коде так чтобы они не попадали в репозиторий? Пример ситуации: я джун/стажер, прихожу на свой первый проект, получаю некую задачу, стягиваю себе репозиторий и пытаюсь как-то в нем разобраться и, разумеется, пишу комментарии, поясняющие работу тех или иных кусков кода. Затем выполняю поставленную задачу и делаю push обратно в репозиторий. Как сделать так чтобы мои «заметки по коду» не попали в master?

Comments

[Сергей delphinpro]

Хочу — индексирую целые блоки, а хочу — только выделенные строки. Atlassin SourceTree.

скриншот

[mkone112]

Сергей delphinpro, а обратно по идее нужно будет делать merge?

[Сергей delphinpro]

mkone112, Вы проиндексировали только то, что должно улететь в общую репу. Остальное висит у вас не закомиченным.
Если нужно слить свежак с удаленного репо (git pull), то свои комменты можно временно спрятать (git stash), сделать pull, а потом достать из стэша.
Да, это лишние движения, неудобство. Но придется потерпеть, раз вам сложно без своих комментариев. По мере накопления опыта и знаний, вы постепенно откажетесь от своих комментариев-подсказок.

[mkone112]

Сергей delphinpro, Звучит супер-круто. А можно делать это без Atlassin SourceTree? Скажем в git из консоли, или может есть какой-нибудь плагин для PyCharm?

[Сергей delphinpro]

mkone112, Разумеется можно. SourceTree — это всего GUI оболочка на консольным гитом. Под капотом она выполняет всё те же команды.
Но конкретно этот кейс - выделение и коммит отдельных строк - ужасный геморр в консоли.

Что касается PyCharm? то это ведь от jetBrains прога?
Значит там так же, как и в phpStorm:
Вызываете окно коммита

spoiler

Но в этих прогах не такая тонкая настройка. Они могут включить/исключить из коммита только целые блоки кода, не отдельные строки.
По отдельным строчкам SourceTree единственный на рынке. А перепробовал я их все с официальной страницы гуи-клиентов на сайте гита.

[Сергей delphinpro]

и, нет, это не круто.
Со временем у вас так может набежать много незакомиченных комментариев, которые всегда будут висеть на виду. Вам будет сложнее ориентироваться в том, что нужно отправить в общую репу, а что нет. Рано или поздно вы ошибетесь, отправите лишнее, или не отправите нужное.
Лучше прислушайтесь к советам других людей, а описанный мною кейс используйте для того, чтобы отправлять чистые и аккуратные коммиты без мусора.

[mkone112]

Сергей delphinpro, Я бы отметил ваш комментарий решением, но видимо это невозможно.

[Сергей delphinpro]

mkone112, Вопрос должен быть с решением, раз оно есть =) Отмечайте ответ ниже.

Answer 1

[Сергей delphinpro]

Хочу — индексирую целые блоки, а хочу — только выделенные строки. Atlassin SourceTree.



Детали в комментариях выше :)

Answer 2

[Владислав Лысков]

Есть такая штука, блокнот называется, вот в ней и делаете для себя пометки

Comments

[mkone112]

Комменты отдельно от кода не слишком удобны для восприятия.

Answer 3

[Aetae]

Если впоследствии тебе самому эти комменты не нужны, то просто заводишь свой git hook (написанный тобой же на удобном тебе языке), который перед отправкой будет затирать в файлах твои особые комменты(напр по какой-то метке).
Если нужны, то вроде были плагины для разных ide позволяющие писать комменты к файлу(не в коде), погугли для своей.
Удалять комменты перед отправкой и вставлять обратно в код - не вариант, знатный геморрой возникнет с мержами и разрешением конфликтов.

P.S. Вообще просто пиши комменты аккуратно и заливай их вместе с кодом. Документирующие комменты вовсе не лишние.)

Comments

[mkone112]

Если впоследствии тебе самому эти комменты не нужны, то просто заводишь свой git hook (написанный тобой же на удобном тебе языке), который перед отправкой будет затирать в файлах твои особые комменты(напр по какой-то метке).
Если нужны, то вроде были плагины для разных ide позволяющие писать комменты к файлу(не в коде), погугли для своей.

А если комменты нужны впоследствии, но я хочу видеть их как обычно - прямо в коде?

Вообще просто пиши комменты аккуратно и заливай их вместе с кодом. Документирующие комменты вовсе не лишние.)

Думаю мои банальные заметки никому кроме меня в репе не нужны.

[Aetae]

mkone112,

А если комменты нужны впоследствии, но я хочу видеть их как обычно - прямо в коде?

...не вариант, знатный геморрой возникнет с мержами и разрешением конфликтов.

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

[mkone112]

Aetae, а как вообще без этого живут? Держат заметки отдельно или в голове? Каждый раз разбираются в коде по новой? Довольствуются документацией?

[Aetae]

mkone112, ну какбэ очевидный код - очевидный, неочевидный код и так должен быть "обкомменчен". А о джунах никто не думает.)
Честно говоря не сталкивался с такими проблемами, так что ничего конкретного посоветовать не могу.
Разве что просто делать себе в том же пре-коммит хуке создавать(пере-создавать) себе ветку <имя>_comment в которую комминтить коммент и переключаться на оную когда надо обновить в памяти кусок кода, без мержей. Но это так-себе решение.

[mkone112]

А о джунах никто не думает.)

Я начинаю понимать...

[Евгений Самсонов]

mkone112, хорошо написанный код это и есть документация)

[mkone112]

Евгений Самсонов, Хорошо написанный одним человеком код. Может быть очень плохо восприниматься другим, из-за разницы в опыте.