Claude Code 2.0

Comments are often the best tool for explaining why a bit of code is formulated how it is, or explaining why a more obvious alternate implementation is a dead end.

An example of this: assume you live in a world where the formula for the circumference of a circle has not been derived. You end up deriving the formula yourself and write a function which returns 2piradius. This is as simple as it gets, not hacky at all, and you would /definitely/ want to include a comment explaining how you arrived at your weird and arbitrary-looking "3.1415" constant.

Avoiding comments is an exercise in thinking how to rename or refactor a function, or a variable in such a way that a junior developer will be able to read it like prose, and immediately understand what's going on.

It's cognitively stressing, but is beneficial for juniors, and developers new to the codebase, just as it is for senior developers to reduce the mental overhead for the reader.

It's always good to spend an extra minute thinking how to avoid a comment.

Of course there are exceptions, but the mental exercise trying to avoid having that exception is always worth it.

Comments are instant technical debt.

Especially junior developers will be extremely confused and slowed down by having to read both, the comment, and then the code, which was refactored in the meantime and does the opposite of what the comment said.

I recall a study that said AI coded much better when in codebases with dense commenting.

I'm wondering if tsdoc/jsdoc tags like @link would help even more for context

You need to use comments, when your code doesn't make sense to the reader. A way better approach is to write code which makes sense to readers. There are cases when you need to write incomprehensible code for the sake of performance, for example, but that's rare. Even in high performance environments. Or maybe you need one for some bugfixing. But most of the strange "bugfixing", or performance "improvements" what I saw in my life was just technical debt, and coders were lazy, or had time pressure. It's really very rare when you really should use a comment. When I think about writing a comment, I immediately think through, or look into more whether there is a better approach. Usually, you can use Git, or Git+ticketing systems anyway for business reasons.

So far Clause Code's comments on my code were completely useless. They just repeated what you could figure out from the name of called functions anyway.

Edit: an obvious exception is public libraries to document public interfaces, and use something like JavaDoc, or docstrings, etc.

Thoughtful comments can provide the why, but they can just as easily be a redundant re-statement of the what in the code, which llm comments quite often are.

Most Claude Code comments answer the "what", or worse they answer the why in a way that makes no sense outside the context of that session. Stuff like adding a comment saying why they removed our changed code that they'd just written

Ah, thank you, that's a great sublety that I missed before!

Yeah this is definitely a useful feature. I use git add for good passes, but this eliminates more manual work

Ugh, no. Git is a distributed vcs. Changes in git stay local unless and until you push them to a server, and then furthermore, point someone else at your changes for review. (Formal PR or otherwise.)

Your tools should work for you, and git is no exception. Commit early and commit often. Before you (or an LLM) go on a jaunt through the code, changing whatever, commit the wip to git as you go along. That way, if something goes awry, it's an easy git reset HEAD^ to go backwards just a little bit and undo your changes.

Later on, when it's time to share your work, git rebase -i main (or wherever your branching off point was). This will bring up your editor with a list of commits. Reorder them to make more sense, and then also merge commits together by changing the first word on the line to be "fixup". exit your editor and git will rewrite history for outside consumption. Then you can push and ask someone else to review your commits, which hopefully is now a series of readable smaller commits and not one giant commit that does everything, because those suck to review.

If you're using AI like this, it seems to me that it would be perfectly reasonable to make a separate branch, allow for micro-commits, and squash once a "complete chunk of work" is done.

That said, having a single option that rewinds LLM context and code state is better than having to do both separately.

How could they possibly hope to undo bash commands, whose side effects could be anything, anywhere?

Hey Claude... uh... unlaunch those

I have this in my CLAUDE.md and it works better than 50/50. Still not 100% though:

### Development Process

All work must be done via TODO.md. If the file is empty, then we need to write our next todo list.

When TODO.md is populated:

1. Read the entire TODO.md file first 2. Work through tasks in the exact order listed 3. Reference specific TODO.md sections when reporting progress 4. Mark progress by checking off todos in the file 5. Never abbreviate, summarize, or reinterpret TODO.md tasks

A TODO file is done when every box has been checked off due to completion of the associated task.