Tag Archives: practice

Dump of a few interesting Coding Horror posts

I could spend hours delving through the archives of Jeff Atwood’s Coding Horror blog, but there are only so many hours in the day. Here are a few bookmarked posts I wanted to post links to for posterity.

Security

Programmer comfort

Various

Version control practices

Thoughts on good practice when using version control, based on my experience, and not in any particular order.

Commit one “thing” at a time, where “thing” is a feature or a bug fix. Don’t commit a feature at the same time as a bug fix, or multiple bug fixes at once.

Review what you’re actually committing – the files, and their contents. You may have temporary changes to some files, you might have forgotten to deal with a FIXME, you might have used an editor that’s messed up the whitespace/indentation of entire files.

Sometimes you get called upon to fix something while you’re working on a feature, with some half-done changes in your working copy. Create a branch, switch to it, commit your half-done stuff, then switch back to trunk to fix whatever it is. When you’re done fixing, either continue your work on the branch or just merge it in to trunk straight away and carry on.

Commit messages should say what you did, and if relevant, why (e.g. what issue it fixes). Bad examples are “changed js file”, “fix bug”. If you’re working on a feature and make multiple commits, “<name of feature>” is not a good message.

Learn how to resolve conflicts properly, take care when doing it, and test after merging (even if there were no conflicts). If in doubt about a conflict, ask someone. Learn how to resolve tree conflicts properly. Use a clean working copy for merges.

Learn how to revert committed changes (reverse merge), or ressurect files with history (svn copy).

Preserve history on file moves. Use svn move, or your SVN-enabled IDE to move files. These will track the fact that the file was moved, and the history will remain linked in SVN – this is called “addition with history”. If you just use Windows Explorer, your move will become just a delete and a corresponding unrelated add.

Thoughts on TODOs

I’ve seen many TODO code comments in my life so far, and they’re something I think should be handled with care. From discussion, and online reading, I realise that the best way of using them will vary between people and teams.

The biggest issues in my opinion are:

  • hidden work – there is no visibility in the bug/task tracker/project plan of work that may need to be done based on a TODO
  • accidentally checked in code with TODOs next to it
Examples:
@Ignore //TODO don't check in, fix this test

catch (SomeException e) {
    //TODO do something about this
}

//TODO this whole thing will need to be reimplemented before feature x can be done

A good-sounding method I’ve heard of being used is the following (although I haven’t used it myself):

  1. developers put their name or a bug ID next to TODOs
  2. before each release, remove all TODOs – delete them if no longer applicable, or create tasks for them.
    1. Item 1. helps with this
    2. Remember to include all file types (those that your IDE might not scan by default)
    3. Also applies to FIXMEs

This goes some way to address the issues and avoid TODO-explosion in a project, while not adding too much overhead to day to day development that might discourage developers from documenting issues, improvements and so on using TODOs.