Comments on: Challenge: Do You Truly Understand This Code?

By: The Tests For The Readable Code Challenge

The Tests For The Readable Code Challenge — Sat, 10 Sep 2011 19:21:17 +0000

[...] commentsWritten on February 22nd, 2009 by Davy BrionCategories: Software DevelopmentAfter the uncommented code, and then the commented version of the code, you finally get to see the tests that verify that [...]

By: The Commented Version Of The Readable Code Challenge

The Commented Version Of The Readable Code Challenge — Sat, 10 Sep 2011 19:16:45 +0000

[...] Software DevelopmentBefore i post the tests and a further explanation of the code i listed in the readable code challenge, i wanted to post only the commented version of this code: public class Broadcaster : IBroadcaster [...]

By: Once Again: Comments In Code Aren’t Necessarily Bad | The Inquisitive Coder – Davy Brion's Blog

Wed, 18 Aug 2010 20:28:48 +0000

[...] back up my point, i’d like to point you to this challenge i posted over a year ago. That code is clean. But pretty much everyone could use some comments to [...]

By: Using Copy-On-Write In Multithreaded Code To Reduce Locking Overhead | The Inquisitive Coder – Davy Brion's Blog

Mon, 08 Mar 2010 15:36:44 +0000

[...] leaves the copy-on-write pattern. I’ve used it before with success (though at the time, i didn’t know it was a known pattern) so this approach has [...]

By: sl

sl — Mon, 23 Feb 2009 23:21:08 +0000

There’s no such thing as self-documenting code. Sure, you can always roll up your sleeves and study the code line by line. But when you have hundreds or quite commonly thousands of lines of code, it’s impractical to go through all of them. Regardless of how clean your code is written, nothing beats a few lines of plain English sentences describing what your code does at a high-level (unless you’re writing a “hello world” application).

By: Davy Brion

Davy Brion — Mon, 23 Feb 2009 20:44:53 +0000

@JM

the importance of comments in certain situations, no matter what the purists might say. did you really read the 3 posts including the (post) comments? i kinda figured it’d be clear (the point)

By: JM

JM — Mon, 23 Feb 2009 20:32:25 +0000

This reminds me of a “look how smart I am” blog. Not sure what you were trying to get across in your three blogs on this code. The use of comments? The way foreach works? The I can code neat stuff, can you figure it out (I am in this camp)?

By: vnaranjo

vnaranjo — Mon, 23 Feb 2009 20:08:30 +0000

Sure. You have a List of Clients, and to control the access to the list, you use a Monitor (dummy object, just to ensure threat Safety).

By: Terry

Terry — Mon, 23 Feb 2009 15:17:13 +0000

Without a doubt, I would say that with no “why” style comments the context and the purpose of this code is unclear to say the least. It’s obvious “what” the code does but “why”? Sadly mean code purists don’t understand this fact.

By: James Hart

James Hart — Mon, 23 Feb 2009 10:41:20 +0000

One thing I would say that is overly obscure is the use of a collection initialiser:

clients = new List(clients) { client };

you’re using the collection initialiser here to shorten the equivalent code:

clients = new List(clients);
clients.Add(client);

In this case, I’d explcitly expand that out. The problem is that idiomatically, collection initialisers are typically used to populate a collection object after it has been constructed -empty-. Using it to append an item to a prepopulated collection is non-idiomatic, and distracts from noticing that the collection is prepopulated at all.

Also, looking at your removal code, you might consider, instead of creating a list then removing an item, switching to:

clients = clients.Where(c => c != client).ToList();

though that maybe plays down the list creation; perhaps:

clients = new List(clients.Where(c => c != client));

By: Ben

Ben — Mon, 23 Feb 2009 09:26:39 +0000

I’m not familiar enough with C#, but I would have expected the list variable to be marked as volatile. Otherwise, it can be cached and won’t be seen by all threads until the CPU caches are flushed. At that point, its a standard CopyOnWriteList, and I’d have just made a reusable data structure. This is pretty standard and straight-forward code, imho, and I’ve written similar.

By: Davy Brion

Davy Brion — Mon, 23 Feb 2009 07:17:41 +0000

@Bob

i believe comments are at least helpful in this case because the problem isn’t obvious to everyone nor is the solution

and no, i don’t want a pat on the back for this… it’s funny you think of that. How much functionality would a class need before one deserves a pat on the back from you?

By: bob

bob — Mon, 23 Feb 2009 06:11:12 +0000

Creating a copy on write LIst is OK i guess, if your willing to put up with that kind of overhead.

My confusion rests in your question about comments. This class does almost nothing.
Why would comments be required?

You really dont want a pat on the back for writing 50 lines of clear but essentially minimal functionality do you.

By: Justin Etheredge

Justin Etheredge — Fri, 20 Feb 2009 19:00:34 +0000

You are treating your Lists as immutable and concatenating the new item or removing the old item from a new list. You are doing this because if you are in the middle of a broadcast when a client is added or removed it will cause the list to be modified which will throw a “collection was modified” exception from the “foreach” loop since you modified the iterator. Wow that was one heck of a run-on sentence.

By: Ian Chamberlain

Ian Chamberlain — Fri, 20 Feb 2009 00:05:06 +0000

I think this is to manage concurrency. You cannot support enumeration (as in Broadcast) with write accesses (Add and Remove) at the same time as List instance members are not thread safe. All you would need to get a problem would be *one* add/remove happening at the same time as a broadcast to generate an exception. You either have to lock the List whilst enumerating or not modify it whilst a broadcast is in progress.
If the issue is thread safety I like to indicate that in the method name as in ThreadSafeAddxxx or ThreadSafeRemovexxx.

By: Davy Brion

Davy Brion — Thu, 19 Feb 2009 22:47:24 +0000

i will post a full explanation of the problem, including the comments i added to the code and the tests that protect against the issue and then you can all decide what is more communicative: the comments or the tests

but seeing as how i’m enjoying leaving you all in suspense (i’m rather evil that way), i will do that on either saturday or sunday depending on when i have the time to write the post

in the meantime, feel free to keep guessing :p

By: Ben

Ben — Thu, 19 Feb 2009 22:35:44 +0000

To me, the code is very readable

I agree with Laila that seeing the tests fort his code would show more than comments.

By: Davy Brion

Davy Brion — Thu, 19 Feb 2009 22:34:18 +0000

OK… one hint: in the worst possible scenario (from a load perspective), i’m expecting maybe a couple of broadcasts _per minute_

By: Stijn Guillemyn

Stijn Guillemyn — Thu, 19 Feb 2009 22:04:23 +0000

@Ayende

Indeed. As always, your explanation is more clear, but that’s what I meant with:
probably not something you want giving the fact you want the broadcast to act instantly

You need a way to ensure your code doesn’t break when broadcasting, due to a changing list.
You might lock every access, or use this approach that gives better broadcast performance (which is the main purpose of your class after all).

To me, comments would be advisable. What’s your take on this?

By: Ayende Rahien

Ayende Rahien — Thu, 19 Feb 2009 21:50:28 +0000

I would say that the actual reason is performance.
You aren’t likely to changing the broadcast list all that often.
By having an immutable value, you can avoid locking whenever you need to broadcast.