I think this prooves that having a set of decent tests is gold.
Comments explaining the potential issues are silver.

it’s not an issue with lazy evaluation of an enumerable

with your suggested approach, you could still run into threading issues during the executing of the list.ToArray() call

unless you lock around all writes, as well as around the creation of the array

- If you rewrite the code as below, i think the comments (and the newing up of the clienlist) are not needed anymore,
because the issue with ‘lazy evaluation’ of an enumeration should be more or less obvious:

// ignore changes to the underlying source while enumerating
foreach (var client in clients.AsImmutable())
{
client.SendNotificationAsynchronously(notification);
}

public static IEnumerable AsImmutable(this List list)
{
return list.ToArray();
}

well, as far as this piece of code is concerned, the ‘series’ is pretty much over… i think i’ve already milked it for all it’s worth

I suppose my background (and working environment) is a bit more ruthless than average when it comes to factoring code for understandability that avoids getting comment-happy. In many ways, I suppose I’m more inclined to being ruthless in that manner to help counterbalance the comment-happiness that is prevalent in a lot of codebases. Codebases where comments are used to shore up crap code that itself could easily be made much clearer and avoid the risks of comments where possible (e.g. getting out of sync with the code, what have you.)

To be clear: complicated code should be commented. But only once as many as possible of those comments have been refactored into the structure of the code itself (in the names of members, etc.)

Keep up the great series of posts! I’m really enjoying them so far.

i’ve followed your suggestion… renamed the monitor and gotten rid of the comments in the AddClientToRegisteredClients and RemoveClientFromRegisteredClients methods. So now, i only have the comment block on top of the clients list field and the comments in the Broadcast method. Kinda like the result, thx

As for why i used copy-on-write instead of copy-on-read… i have no idea, this was just the first solution i thought of using. Haven’t tried the copy-on-read yet, but it actually might make it more explicit as to what is going on. You’d have to put locking in all 3 ‘tricky’ places (addition, removal, pre-looping) so to the reader, it might be more clear as to what is going on without requiring comments.

@Jeremy

For you, this code might have been entirely clear from the beginning, but i’m pretty sure that that wasn’t the case for most people who read it. When i posted the original code, a lot of people were asking me for hints in the comments, at the office, on IM, email, etc… So i think the commenting on the ‘why’ does make sense in this example. Oh and i’d hate to see code that you _don’t_ find clear

My personal recommendation would be to save commenting like this for those rare-but-inevitable occasions where code has to do something very specific for a reason that is very obscure and strongly tied to something entirely outside the control of the developer, with your example not counting as such a situation given that it is a general solution to a common problem, not, for example, a seemingly-incorrect-but-in-reality-utterly-unavoidable work-around at a integration point with a problematice external system. In other words, you should never have to comment on who, what, when, or where, and should only comment on why when why _only_ makes sense in this _single_ situation and no other.

I do agree on the fact that some parts of the comments are already obvious from the code itself.
They even remind me of Davy’s post Are women better developers than men?, more specifically the part about the female ‘roadmap-comments’ within code…

The comments “we create a new List instance based on the previous list plus the new client and then we assign the new list to the clients reference that the rest of this class uses” and “we create a new List instance based on the previous list minus the client that needs to be removed and then we assign the new list to the clients reference” pretty much just states what is obvious from the code itself.

One thing that deserves a comment but was left out is why you opted for a copy-on-write instead of a copy-on-read when broadcasting — I assume it is for performance reasons?