18

A common scenario I have is this:

I download a new codebase. In order to have me understand the code, I need to litter it with my own comments about what each section of code does.

It seems inappropriate to then push these messy comments back upstream.

So now I have a problem: my own codebase has a bunch of my own notes / comments, but I don't want to share them upstream with others.

I vaguely researched that maybe I can setup something to remove only certain types of my own comments each time I push, but I don't have a clear resource on the best way to set this up.

Improve this question
9
  • something like this? :youtube.com/watch?v=x1bnNdEx9ig
    – Ewan
    Jul 2 at 9:31
  • 7
    You could always keep your comments in a separate (private) branch, and switch to that when you're doing code-analysis, then cherry-pick your actual changes back to the regular branch when you want to push something upstream.
    – Jeremy Friesner
    Jul 2 at 18:58
  • 22
    If you require code comments to clarify the code, you should ideally talk with your team about readability of the code. With better naming of functions, classes, variables, code should be understandable
    – Tvde1
    Jul 3 at 7:05
  • 7
    @Tvde1 yes. Good comments are nice, but code that doesn't need comments is better.
    – leftaroundabout
    Jul 3 at 7:55
  • 3
    Suggestion: write your own comments, not directly in the code base, but on a separate document. Then, clean up that document, polish it a bit, give it title "An introduction to our codebase", and commit it to the repo. The next new user to the codebase will thank you for it.
    – Stef
    Jul 3 at 14:50

6 Answers 6

Reset to default
49

Simply get into the habit of writing good comments - short, neutral, objective and non-redundant information about why a bit of code is doing what it's doing - and then the authors will probably be happy to have them. Plus, the habit transfers to your own projects: everybody wins.

Improve this answer
15
  • 20
    non-redundant is quite subjective though. A newcomer to a repo will be greatly guided by some comments, which people familiar with the repo might find redundant
    – user3180
    Jul 2 at 19:32
  • 14
    @user3180 I'm pretty sure that wasn't what was intended by redundant. Unless the repo owners are openly hostile to external contributors, they wouldn't consider such comments redundant. What was meant (I think) is the more common and amateur mistake of writing things like index++; // increment index - it looks stupid in this context, but it happens all too often, believe me.
    – Christian
    Jul 2 at 19:47
  • 15
    Any piece of code that is not clear to a newcomer should be commented on. Don't comment on the mechanics. How a code works can be understood from reading the code. Comment on why the code is there and what it is supposed to do.
    – slebetman
    Jul 3 at 2:11
  • 2
    An example of comments for newcomers but not experts are explanations of concepts from heavy APIs, such as Vulkan or Direct3D.
    – Pablo H
    Jul 3 at 15:53
  • 2
    Assuming the code is written well, the only comments should really be about "why" something was implemented like this rather than "what" the code is doing. A newbie wouldn't have that context and almost all of their comments are going to be cruft.
    – ScottishTapWater
    Jul 4 at 8:59
19

Use a junk drawer.

It is perfectly ok to mess with code locally and never push your changes to anyone else. I’ve done this for years.

There is nothing special about code that means you can’t keep drafts of changes you know you can never publish.

The trick is being sure you never accidentally publish this work. //TODO markers can help with that.

I read code with my fingers. I transform it and write comments that only I would ever understand. I don’t show this to others. I use this work to figure out what I should show others.

But the last thing you should do is “maintain” the junk drawer. Everything sent here is meant to die here. That frees you. Use this as stepping stone on the way to code that you can show others.

Remember, in 6 months time you’ll be as clueless as others. So don’t forget that creating truly readable code helps you too.

In short, not everything you write must be ready for the world. It’s ok to have your own notes that only make sense to you.

Improve this answer
5
  • How do we automate this though? For example, perhaps I could pre-pend all my comments I don't want uploaded with some prefix, then I have a script that strips these comments every time I push upstream.
    – user3180
    Jul 2 at 18:05
  • 1
    //TODO: remove.
    – candied_orange
    Jul 2 at 19:06
  • I need some script to automatically strip comments with //TODO: remove
    – user3180
    Jul 2 at 19:31
  • 3
    Was thinking more along the lines of making your push fail when that is detected.
    – candied_orange
    Jul 2 at 21:35
  • I often make selective commits of things I want to remove later, like debug printfs, then when the branch is otherwise ready for merging, I remove those commits. This normally gives me a few conflicts to resolve, but those are trivial.
    – Simon Richter
    Jul 3 at 3:08
11

(All assuming you're using git; most of this should have parallels in any other reputable modern VCS)

I once wrote a git pre-commit hook to fail if it found the text NO-COMMIT in the modified files. That way, I could comment // NO-COMMIT blah and be assured that I wouldn't accidentally commit that comment, and I could also mark files that I felt like I might forget I needed to come back to and clean up.

Writing such a thing to actually remove those comments would be harder, and also it's not good practice for hooks to be modifying code (yes, even linter hooks--they should fail the commit, not modify your commit).

If you're using a GUI tool that makes it easy to commit only certain lines, then the commit hook could be valuable in doing what you're describing. Otherwise, this is quite a pain to do from the command line and I would recommend a different flow, such as keeping notes in separate files. You can set up a local .gitignore to filter out files of a particular pattern, such as **.mynotes.*, and then put notes for foo.js in foo.mynotes.txt.

Improve this answer
4
  • 1
    I disagree with the claim that GUIs are necessary to make staging hunks easier (it’s easier in Vim with Pathogen than with the interactive flags), but I’m not sure if this subtlety is worth editing for.
    – D. Ben Knoble
    Jul 4 at 2:30
  • 2
    @D.BenKnoble if something is easier in Vim, then it's hard.
    – MattPutnam
    Jul 4 at 5:06
  • @D.BenKnoble isn't Pathogen a package manager, which, in itself, has nothing to do with git? gitsigns or Fugitive.vim allow to stage hunks, for example. But as much as I love vim, the process of git add -i is much smoother with vscode + gitgraph than in any vim plugin I've tried.
    – Eric Duminil
    Jul 5 at 12:54
  • @EricDuminil yikes, I did mean Fugitive above
    – D. Ben Knoble
    Jul 5 at 16:31
6

Many modern IDEs have a concept of bookmarks or similar, where you can annotate code / lines with extra information without altering the source code.

That being said, if the codebase you downloaded is lacking documentation/comments to such a level that you had to add your own, then it seems natural that probably some of those comments do in fact belong in that codebase.

On a different perspective, as @kilian-foth already mentioned, it's great to observe a few points when it comes to this subject:

  1. code should be self-documenting - prefer descriptive names over short variables (rowIndex instead of x, i, n... or getUser() instead of user())
  2. similarly, if at all possible, avoid writing comments explaining what should have been clear in code - ie, prefer fixing the code over commenting it
  3. prefer commenting on why instead of what - many badly written comments simply describe what the code is doing (which is typically visible) as opposed to why that is not (typically not visible/obvious)

Back to the original question, if you're using version control, consider making a branch with just your comments - this allows you to "toggle" your changes just by switching branches (and updating/rebasing your branch in case of upstream changes)

Improve this answer
3

git is your friend whenever you need to maintain private additions to a codebase. Independent of whether it's a good idea to maintain such private additions in the first place. I would handle it like this:

  1. Create a new branch private-additions and check it out.

  2. Add any comments and other private things you want and commit them to private-additions.

  3. If you ever create something you do want to publish, commit it to master or some other feature branch that does not know anything about your private-additions branch. This can easily be published in the normal way.

  4. Whenever you fetch new changes from upstream, simply merge them into your private-additions branch or rebase it onto the upstream master. This allows you to look at the new code with your old additional comments.

Since the changes on private-additions are never merged into master, you retain a pristine view of the upstream repository. However, whenever you checkout your private-additions you get your own commented view of things.

Only downside is, that it can get a bit messy to peel things apart should you accidentally commit changes for publication to your private-additions branch or the other way round. Nothing that can't be sorted out with git rebase -i, but something that should be avoided nevertheless.

Improve this answer
1

I developed an own annotation system for comments where I start certain "temporary" comments with a specific word:

// TODO: Add a proper rating algorithm 
ratingScore = 1.0f;

// NOTE: Factors I should take into account: Proximity, difficulty, risk, reward

// DEBUG:
Debug.Log(ratingScore);

It's easy to scan source files for such comments, both visually and tool-assisted.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.