Comments on: Programmers as Channel Surfers

By: Amit Jain

Amit Jain — Sun, 16 Dec 2007 00:07:39 +0000

I like the unit test strategy for ‘ToDo’ things.
We , generally, write unit test cases againt the functionalities which are yet to be implemented and these unit tests keep failing till we implement them.

Infact, in our project, we often follow test driven methodology where we write test cases at the start and implement functionality to make the unit tests pass.

By: Bill Kayser

Bill Kayser — Wed, 17 Oct 2007 23:41:59 +0000

The way I deal with it is defining my own tags. In Eclipse you can define new tags to appear in your task list, with different priorities. So I typically use WHKTODO for my own list of things to follow-up on.

By: Deepak Nohwal

Deepak Nohwal — Wed, 17 Oct 2007 06:05:58 +0000

Throwing UnsupportedOperationException() is a pretty good idea that I follow in my code. However, one cannot always do that. For example, places like where you want to do some optimizations in the code but you cannot do due to lack of time.

// TODO:: Use MDBs insteadof Threads here.

Now, things like these are often put up as TODO comments in the code but they are not trivial enough to be done immediately or even in a code review. Not sure how we tackle this problem of these not-too-many TODOs. Thoughts?

By: Bill Kayser

Bill Kayser — Wed, 17 Oct 2007 05:24:28 +0000

That’s pretty definitive! But I like it. Even better is to write a unit test that calls the method. Then you don’t have to wait for a tester to trip over it, it shows up as a “to-do” every time you look at your unit test results, showing it as a failure. I usually throw UnsupportedOperationException().

By: Ramesh

Ramesh — Tue, 16 Oct 2007 12:10:29 +0000

For very important TODO comments like Vaibhav mentioned:
//TODO: Implement the code to save the record

I prefer to put exception so that this could be easily figured out by developer (or tester in case developer is not doing the basic testing ).

e.g.
throw new ApplicationException(”Save not implemented.”);

I am not sure what is the best way of doing this. Any comments?

By: Vaibhav

Vaibhav — Mon, 15 Oct 2007 21:11:16 +0000

I agree… this doesn’t work at all if you let the markers gather around. There needs to be a very disciplined approach to take care of these markers on a couple of times a week basis, if not on a daily basis.

If the list becomes too big, it is very easy to lose sight of that important // TODO:

//TODO: Need to rename this variable…
vs.
//TODO: Implement the code to save the record

In that sense, //TODO: comments are not all that different from normal comments. You need to know when to put which…

By: Bill Kayser

Bill Kayser — Mon, 15 Oct 2007 15:32:12 +0000

That’s a good policy. Eclipse does the same thing. It’s interesting though, that at some point on the project I’m working on now, it just became noise. When the current team took over, we found that view was filled with thousands of markers, FIXME’s and TODO’s, nearly all completely pedantic. Their intentions were probably good. I think what happened was they started this practice before using IDE’s that could show them all in a single list view.

By: Vaibhav

Vaibhav — Mon, 15 Oct 2007 06:17:35 +0000

Right… in .Net (and I keep referring to that, because I have little Java experience)… I personally do and also encourage my team members to leave //TODO: comments.

The Visual Studio IDE lists ALL TODOs in a Task List whenever code is compiled. This way, a simple review to check if there are any pending TODOs helps wrap ends up before code commit/release.

By: Bill Kayser

Bill Kayser — Sun, 14 Oct 2007 21:21:51 +0000

Also reminds me of the two flavors of comments I see all the time in our legacy code:

// HACK ALERT Really should be doing this thread safe…

// FIXME Need to localize this…

The first is like a pre-emptive strike described in that article, a little disclaimer added to soothe a guilty conscience.

The second is practially a joke. I’m sure a lot of developers think they’ll go back after the release and fix all these, and maybe some do, but I see hundreds of these in code that hasn’t changed for years. It’s like the advice I give new homeowners lamenting the fixup jobs they inherit when they move in: If something looks like it needs a repair or paint job, leave it for two months. After that, there’s a good chance it won’t bother you anymore and you won’t need to fix it.

By: Vaibhav

Vaibhav — Sun, 14 Oct 2007 19:57:37 +0000

Another good use of comments is to send messages to the next developer who will inherit your code as to why you used a certain non-obvious way to implement things. I was reminded of this while I was reading a post by Phil Haack. The complete post is here:
http://haacked.com/archive/2007/10/07/the-greatest-compliment-a-developer-can-receive.aspx

By: Manas Fuloria

Manas Fuloria — Sun, 14 Oct 2007 02:01:08 +0000

Bill, I’m really enjoying this.

Just FYI, since we worked together I’ve become a convert to the importance of usability. Everything we do as engineers is to enhance human experience – our own or that of others. (Even if you are designing a bridge – you don’t want your users to get wet, right?!) It takes a lot of introspection and self-criticism to make human factors truly influence your design, but the results can be delightful.

By: Vaibhav

Vaibhav — Wed, 10 Oct 2007 08:06:07 +0000

Well I can mention my experiences as a .Net developer and the best practice that we have propagated in Nagarro mandates the use of _ prefix for private scoped variables at the class level.

Personally, I feel that the IDE intellisense is better utilized because pressing _ immediately filters the available options to only your private variables, which is really useful.

But yes, I used to understand Hungarian in terms of including type information to the variable, but that (as you said) is not needed anymore. Earlier it was for informational and guiding purpose to reduce chances of type mismatches.

However, I really like the Apps Hungarian concept a lot and would love to integrate it more and more into coding practices.

By: Bill Kayser

Bill Kayser — Tue, 09 Oct 2007 18:23:40 +0000

Very interesting. I guess I’d forgotten that the term referred to a notation that had more to do with the type of the variable than it did the scope. I’m kind of embarrassed because that’s not at all what I had in mind. I don’t think in Java with modern IDE’s that there’s much benefit to encoding the type of a variable in the name. Encoding the scope, however, I find useful. A prefix that indicates a member variable, parameter, or static. There’s a common idiom for final statics using ALL_UPPERCASE which is useful.

I’d really like to know what other opinions are on the modified version of Hungarian notation where you encode the scope. I always liked the convention from C++ of prefixing member variables with an underscore, but there doesn’t seem to be a lot of affection for that convention among Java developers.

By: Vaibhav

Vaibhav — Tue, 02 Oct 2007 10:59:16 +0000

I didn’t know this till some time ago myself. A lot of us think of Hungarian notation only as prefixing type information to the front of the variable, however that is technically Systems Hungarian and not the more useful Apps Hungarian (which involves prefixing functional information to the variable name). More on Wikipedia:
http://en.wikipedia.org/wiki/Hungarian_notation