Hacker News Reader

I think it makes sense to refine the levels a bit more. We use FIXME, TODO and OPTIMIZE in order of decreasing importance.

- FIXME should really not even be committed, except in a proof of concept

- TODO should be fixed eventually, preferably before release to production

- OPTIMIZE is a "nice to have" that gets fixed on a quiet day

Furthermore, TBD (to be done) indicates where new expected functionality is expected to appear, deliberately different from TODO because the JetBrains editor flags TODO / FIXME for confirmation before commit, and will ignore TBD.

I was actually just thinking about implementing this type of importance based flags.

In addition to these, I'd like review stubs. Something like:

- REVIEW: can this be done better?

I'd like junior devs to be able to note things as they're thinking about it, not try and remember it later during review. Especially since there may be nothing wrong with the code, it may be as good as it can get[1], so a reviewer wouldn't catch it. Though, I'm mildly concerned about cluttering up code. I suppose you could just remove them on the fly down the line, since they made it past review and etc.

[1]: As good as it can get.. that the reviewer knows of heh

> RE point 2., it also applies to issue trackers and other "proper" way of encoding TODOs - if I tried to branch out to file a ticket in such situation, or even make a TODO entry in the Org Mode files that always accompany my projects, I'd very quickly lose the flow. Context switch is deadly here.

It sounds like the ideal thing to do here, in order to stay in flow, is for these notes to be inline TODOs while coding, but for them to somehow get turned into issues before anyone else sees them. I.e. by a pre-commit hook, or by whatever tooling you use to squash commits when building PRs/patches. If you write them in a standardized format, something should be able to parse them out.

Yes, and it's entirely doable. In case of my own Org Mode notes, I could probably hack together something that does that pretty quickly in both directions (move the note from source file to Org Mode, and display notes from Org Mode inline in the code, at appropriate places). A small alteration could make this work with an issue tracker API.

But that would still be very fragile. I don't think there's a good way to record spatio-temporal coordinates of a piece of a file in a way that's resistant to changes. The usual way is to record file position + preceding and following context, but that'll break whenever someone does some bigger changes immediately around the note you're tracking. Perhaps there is some good trick to solve this, but you have to ask yourself - why go to all this ridiculous amounts of trouble to avoid putting TODO notes in comments? It's not like most of them would fit well in an issue tracker either - they tend to be too small or too context-specific to form a nicely packaged unit of work, and making this level of detail visible to managers is just tempting them to cause a disaster for the company.

Beyond it being pretty fragile to have pre-commit hooks edit code, the problem is TODOs are usually very context sensitive. They are usually only understandable given the surrounding code and part of their benefit is they follow refactorings. Tickets wouldn't have that.

> if I tried to branch out to file a ticket in such situation, or even make a TODO entry in the Org Mode files that always accompany my projects, I'd very quickly lose the flow.

Why not both? You can refactor todos with a ticket number before you commit the code. So the TODO can have some more context associated with it and maybe a discussion.

I might do that after I'm done with the code and about to commit it, but in my experience, there's very little overlap between the kinds of things you'd want to track on your company's issue trackers and the things you want to just jot down inline with the code. The latter tend to be too small.

> I date them all. I have a Yasnippet for all the above, which expands "todo" into "TODO: $ -- My Name, 2019-12-30", $ being where the caret stops after expansion. Same for "fixme", "hack" and "note".

why is that necessary ? git blame gives it to you already

Because running git blame on code breaks the flow. Because git blame may give you wrong author and date (say someone edited the code around the note, changing its indentation level; EDIT: or rebased it, as 'daemin says). Because git blame is not a grep-friendly solution. Because code sometimes lives longer than version control systems (I've worked with codebases older than git). Because very often code lives longer than the repo it originated in, so you can easily lose history (many new projects get started by copy-pasting pieces of a previous project).

I agree with all your other points but I want to point out that if `git blame` breaks your flow I recommend that you look up how to better integrate git with your code editor, it's a huge time saver IMO. With vim-fugitive I can just ":Gblame" on any code I'm currently browsing and immediately I get a side-pane with the annotations for every line. ":Gdiffsplit" shows me the diff between my version and HEAD etc...

But beyond that I agree completely, `git blame` is not the right way to track the authorship of annotations in a file.

It's C-x M-g b in my Emacs, but doing this annotates the whole file, which gets distracting enough for this particular purpose. Still, I use it frequently.

You can rewrite the git history when you squash commits for example.

One case I've heard is that some people no longer have their names on git commits they made to various Google open source projects because their commit went inside, where it was rebased, merged, integrated, squashed, and then what the public sees is a single git commit by a Google insider that is the result of thousands of individual commits.

This is a beautiful example of the general case «why don’t you just use X tool that was designed for this?» but can’t because someone made a decision that makes X tool unusable.

Workflows are full of trade offs. Different people & teams value different features in different ways. It’s what makes software development such a vibrant ecosystem.

I don't understand the need to rewrite history. This is a good example against that practice.

Because it becomes more compact. Most of the time git commits are things that don’t make sense to have at a more macro level. Squashing into a single commit that represents a coherent improvement, particularly for large projects, is the best way to read its history.

I prefer a small branch with many individual commits (cleaned from fixups or not) and a merge with main branch which adds the whole feature. Then you can have two levels of reading.

Doesn't this still put all the commits on the main branch?

No you commit in feature branches then merge to main branch.

Do you then keep the branch around forever?

The branch history is preserved in the commit graph of the main branch, so you don't need to keep the feature branch.

You can keep the branch commits for detailed history, and look only at merge commits the when you don't need details:

     git log --first-parent -m

This will show a linear history of merges, treating the merged code as being added in the merge commit. You can add -p to see the diffs.

But then does it matter at all that the date of the comment was the day where you committed the todo, or two days after when you squashed it ?

At least these days co-authorship can be recorded in the commits.

That’s just conflating GitHub support of these tags with git. Similar "Signed-off-by" tags are in use by Linux kernel pretty much since forever.

But then cherrypicking doesn;t preserve commit metadata, does it?

There are many contexts where blame info is not visible by default: dumb editors, code review browsers, search results, etc. It's a low-effort signaling about the age of TODO as well as whether the person who left it is still around.

It's a similar reason for why you sometimes leave implementation comments in the code, not in git commit messages.

Out of curiosity, is there any disadvantage in making the TODO comments and then removing them before merging the result into master?

In my eyes, yes.

I'm quite thankful if the code I'm reading is honest and tells me about stuff not up to par with whoever wrote the code/reviewed it expected.

With a TODO it can often be easy to figure out if the feature/bug I'm working on is affected by it.

Potentially a huge time saver.

That's a fair point regarding visibility. I'll have to reconsider the pluses and minuses because before now I only really saw it as a "too lazy to make a ticket" thing.

Yes. At that point in time, these comments are by definition a list of things that still needs to be done. Removing that will lead to forgetting it, and may create a false impression that the committed code is 100% complete.

By removing it I mean moving it into the appropriate bug/issue tracker.