4

I just realized that I prefer writing TODO notes directly in to the latest commit instead of issue tracker, for example:

TODO:
- Remove console.log
- Check that XY works
- ...

For example if I have to switch to another job, finishing it and coming back to this branch I can see what had I left undone, fixing it, commit --amend, removing the TODO statements from the commit message.

Is this a good habit or should I force myself to use the issue tracker and write every little notes there (even if others can see the issue)?

bimlas
  • 2,359
  • 1
  • 21
  • 29

2 Answers2

8

I'd say it is sub-optimal.

Consider this: if a TODO refers to code it should be next to that piece of code. If you write it in a commit message, it becomes completely detached. How is your fellow programmer to identify where to look when she wants to implement the TODO?

If a TODO refers not to code, but to infrastructure, documentation, etc., it is much better to maintain a TODO file because it is much easier to

  • find the list of active TODOs
  • move an item to DONE (e.g. simply delete it)

Imagine you want a list of TODO items. In your approach, can you grep all commit messages? How do you know which TODOs are DONE? A separate file makes this answer super easy.

Jens
  • 69,818
  • 15
  • 125
  • 179
  • 1
    Writing TODO as a comments seems to be good idea (just noticed that my IDE has a dedicated "TODO finder" panel). – bimlas Jul 10 '18 at 08:39
  • Just did a git alias to find TODOs added to current branch: `git --no-pager diff --color-words --no-color --diff-filter='AM' master | grep TODO | git grep -f - -F 2> /dev/null` – bimlas Jul 10 '18 at 10:34
0

going back and invoking commit --amend is rather thought for casual fixes, not for regular workflow.

If you pushed your branch already then you will invalidate commits seen by others.

In the situation when issue tracker is an overkill - I can totally understand that - just keep separate TODO file in whatever form, plain text of markdown for example, then add its changes to your code commits.

Wojciech Kaczmarek
  • 2,173
  • 4
  • 23
  • 40
  • If I adding the TODO to the commit, then I should delete the completed items from it ->`commit --amend` the changes. I don't see the differences between storing the notes in a file and in the commit message. **EDIT:** Ok, misunderstood your answer. So you saying that I should commit every little prettifying in different commits. Well, I don't like this, but it's another question (to squash or not to squash). – bimlas Jul 10 '18 at 08:18
  • @bimlas Note that modifiying/amending commit messages is a big no-no in many environments, and rightly so. History in general is unchangeable,. – Jens Jul 10 '18 at 08:23
  • "History in general is unchangeable": then what's the purpose of `rebase.autoSquash` in Git config - I think there are a lot of people prefer clean log over keeping every commit. – bimlas Jul 10 '18 at 08:41
  • @bimlas not sure about 'commit every little prettifying' approach - this seems to be your own idea. I usually do lot of code commits and edit one line on TODO file once some functionality is done, after a merge or similar. So it's avg one change in notes for a dozen of commits. Not much overhead. YMMV – Wojciech Kaczmarek Jul 10 '18 at 08:48