While leaving "private comments" on a repo can be incredibly useful, it can get you into trouble if the wrong person sees them and disagrees with what they see. This post goes into the problems, consequences, and things that tools that provide this functionality need to do to protect their users from accidental harm.

A while ago I wrote a tool called "Private Comments", which allows you to leave "private comments" on a codebase that aren't actually in the codebase. Imagine leaving little "breadcrumbs" for the future you that are actually attached to the relevant lines of code, and go away when that code changes, but reappear if you need to look at the relevant past version of it. It can be used for you, or shared with your team.

That's Private Comments. It's a teeny little server that runs on your computer, takes up almost no memory (~7Mb) and essentially no CPU (~0.0% at idle), and a plugin in your favorite editor¹ talks to it and records or shows comments when appropriate.

There are two types of sensitive data in Private Comments.

1. The content you write.

   1. This could be sensitive in the sense that it contains comments that, if exposed publicly, would violate your NDA. For example, leaving a comment which summarized how a sensitive process works.
   2. This could also be sensitive in the sense that when you give someone a blank notebook labeled "Private" and tell them they can write anything in it without others seeing, it's just a matter of time before they write something that others would take offense to.
2. Metadata about the repo and its files the name of the repo, and the path to the file you're commenting on could be incredibly valuable to hackers. As such, Private Comments goes out of its way to never store this information. So, we can mostly ignore this problem.

Focusing in on the content you write:

1.a. is pretty easy to address. Just don't store your comments anywhere that violates your company's security policies. It doesn't matter who sees it, because all the people who can see it have signed the same NDA as you.

1.b. is the problem, and it's a problem in multiple ways. Let me lay out the ways I see comments being stored that could get a person in trouble if their coworkers saw it.

1. You leave notes about things others find obvious, self evident, or ridiculous to even consider leaving a comment about.
2. You leave "too many" comments.
3. You leave comments they disagree with.
4. You leave frustrated, disparaging, or unkind comments.

Depending on who finds these comments, their feelings about you, and their current state of mind, the results could range from simply lowering their opinion of your capabilities, to you getting fired. If you're working on a client's codebase it could be you and your team loosing the contract.

Keep in mind that developers generally have a low opinion of comments in code, and the comments stored in Private Comments are the things that you've decided shouldn't even be a public comment.

On top of this, most devs don't value the concept of Private Comments, and most folks in American society (and many others) are terrible about understanding and empathizing with neurodiversity, or people who see the world differently from them.

For example: I have ADHD. As a result, my memory is terrible. Like, ended up with a nail through my nose because of how bad it is. However, when someone finds out I've forgotten something important, I'm blamed. I "didn't care enough", or "must not have been paying attention". There's no consideration for the fact that my brain is physiologically different.

As a result of this poor memory, I leave myself a lot of notes. I then forget that I've left myself those notes. Thus Private Comments so that the notes I leave myself about code are in the code where I need to see them. Even though my comments tend to be purely factual, there's essentially no positive outcome to anyone else finding my comments.

Because of these issues I see it as critically important that Private Comments are never stored in the repo that you're commenting on. I don't care if you use Private Comments or one of its competitors². I do care about you getting screwed over by a tool that accidentally reveals your private thoughts to others. I don't care how innocent those thoughts are. They can still be perceived badly by others, and used to hurt you.

It's important that Private Comments, or any tool like it that you consider using or creating must:

• Never store comments in the same repository or folder structure.

  • Your "private" branches can get accidentally pushed.
  • Your "private" files can get accidentally added to commits.
• Support encrypted comments

That's it really.

PC takes the additional step of never revealing metadata about the files you're commenting on, but it could be argued that that's overkill.

The system must allow you full control of your comments, and make it impossible for those comments to accidentally become shared with the code, even if they're not in the code.

Note: To date none of the Private Comments editor plugins support encryption. It wouldn't be hard to add symmetric encryption in the plugins if that was important to you. The server doesn't care what text you're storing as a comment and has no idea if it's encrypted or not.