[self note]

While working on the most recent patch to Hazel, I stumbled across some code that made me scratch my head. It seemed the code was unnecessary and was causing the bug I was trying to fix. I ended up removing that code while doing the fix thinking I must have been drunk/high/had a gun to my head when I wrote that code originally. Initial tests seemed to confirm it as things were working at first. A couple days later I discovered an older bug had resurfaced. Sure enough, I began to realize why I wrote that odd piece of code back when. I ended up backing out my recent changes and making the fix with the original code intact. I also made another change which was to comment the code explaining why the hell I wrote it that way in the first place.

[self now] != [self future]

One of the nice things about being a solo developer is that you don’t have to deal with the overhead involved when working on a team. You don’t have issues with miscommunication that you would when working with others. Or do you? Like it or not, you are still a team. Sure, you probably don’t need to communicate things with someone else about a current issue, but you, yourself, now, is not the same person as yourself a year from now. You’ll find many times that intentions are lost through the annals of time so documenting things as if there are other programmers on your team is a worthy exercise. Comment your code. Write descriptive commit messages. Edit your wiki. Your future self will thank you for it.

Category: Debugging, Programming 8 comments »

8 Responses to “[self note]”

  1. Marcel Weiher


    Better: write a well-named test.

  2. Scott Gardner

    So true! I have lost count how many times a comment to myself has save myself’s ass.

  3. Ed Hartley

    This is the first rule of good programming and the last, no matter how often you get reminded of it good post.

  4. Warren P.

    I call these bugs “bigressions”. Add something, fix bug A and create bug B. Take it back out, and it fixes B, reintroducing bug A. It’s a cycle in a graph. One of the reasons why version control rocks is that you should be able to identify these cycles, even when multiple developers ARE involved. Hopefully comments help you and other developers not to make such cycles last forever.

    But these are good times to ask yourself about your unit test coverage, and also, about the possibility to refactor your APIs so that such problems become less likely in the future. 90% of patches seem to be of the “if SpecialCaseX then ExecuteHackY”. And 90% of the cruft in all my apps seems to be these patches.


  5. deeje

    the trick is to not go overboard. good objective C reads well by itself, so comments are noise. Its the “fixes” that need to be documented, anytime you say to yourself “wish I didn’t have to do it this way”.

  6. mr_noodle

    Thanks for all the comments.

    Unfortunately, this was for some GUI interaction that is not readily tested in an automated fashion but yes, tests are great for catching these things early but they don’t necessarily communicate intent.

    And yes, you don’t want to go overboard but I find that, especially without other people around to keep you honest, many of us tend be sparser with documentation.

  7. Mason Kelsey

    Usually the worst critic of your own code is yourself. There is enough of the attitude that we can do nothing wrong that we do. Documentation is the characteristic of a thorough programmer who remembers the consequences that happened when he or she didn’t remember what the prior modification was for. It also helps to add a date stamp of when it was added, to the right of each line of code, with the which ties back to a short paragraph of comments at the beginning of the module describing the reason for the change.

  8. Tony Edgecombe

    I think this is the reason why project rewrites are almost always a bad idea. In any reasonably sized project there is a lot of embedded knowledge wrapped up in the code, you never appreciate the importance until customers start complaining when it isn’t there.

Leave a Reply

Back to top