Brian Marick, in a related blog entry, discusses an interesting perspective on the issue of comments in source code. As he frequently does, Brian brings another dimension and perspective to the topic. Brian discusses the expectations of your audience and provides an example of code in C, that if directly translated to Lisp, is not too easy to understand. The "mis"understanding exists because of the generqally accepted style for Lisp code, which is different from C code.

This caused me to think of another example. Lately, I work with C#, but still work with Java from time to time. Java has anonymous inner classes, C# does not. In many cases, anonymous inner classes improves the clarity and simplicity of the code. Given the similarities between C# and Java, I tend to read Java code with my C# hat on, which always causes me to pause when I read code that uses anonymous inner classes.

Should this code have comments, explaining the intention and use of the anonymous inner class? From one reader's point of view, the code may be clean and not need comments, but another reader, as in my example, might benefit from them.

However, I think it is a death spiral if you attempt to accomodate too many perspectives. Do you comment Java for C# readers? What about Java for Ruby, Lisp, Prolog, Python....readers?

Let's assume you only consider the experienced Java reader. On the refactoring group, I see many different opinions regarding the best style and constructs for any particular code snippet.

I don't think this justifies source code comments. Comments assume that the language (English for example) and the prose is readable by all, or at least more than the code. (There is also the issue of keeping the comments in synch with the code as it changes, which is one of my primary practical reasons against comments.)

These considerations cause me to realize something: both the definition of clean code and explanatory comments make assumptions about the reader, her context and her experience. This is true about any writing, but it is particularly complicated for the software developer. The expected future reader can vary dramatically but will probably be faced with some practical reason to quickly understand and use (modify or integrate) the source code and accompanying comments.

This leaves me with more questions than any conclusions. Though I still think a developer should challenge himself to improve his code before he writes a comment, I wonder for whom should the code be made more readable?

I have been ranting for a while (see this post) that the agile development literature is severely lacking. I am mostly concerned with the actual implementation of an agile process and all the real world issues that arise.

"How do you train a customer to be a good XP customer?" , "How can you be a good coach?", or "How do testers fit into XP?" are examples of questions that frequently arise when a team embarks on agile development. Most of these questions are very context specific, so I think it is premature to make any proclamations about them. However, there is a variety of relevant experience that could be useful to those considering such questions.

So, rather than continuing to whine, I am trying to do my part for a solution. I have set up a wiki at http://www.christiansepulveda.com/cgi-bin/moinwiki/moin.cgi/ImplementingAgileProcesses

I am also mining the various Yahoo groups (and other sources) on agile development and adding links from the wiki to relevant discussions.

I hope the wiki will be a resource for those implementing an agile process. Who knows, maybe it will grow into an interesting article or, more ambitiously, a book.

I encourage you to browse the wiki. Email me if there is something you think is missing or feel free to add it. (Please just follow the wiki guidelines on the front page.)

P.S. There is a related project, at http://www.berczuk.com/wiki/bin/view/Agile/AgilePatterns. It is a catalog of agile process patterns. It is a topic I have been interested for some time. Unfortunately, we haven't made a lot of progress (at the time of this post), but there should be lots of entries soon.

I was reading a rather long winded comment in some source code and I started to hear the voices in my head rant about comments in code. This particular comment was written by a rather bright individual who insists on commenting his code. (To make matters worse, he uses C# regions to "hide" particularly long comments, reducing the comments value.)

Not all comments are bad. But they are generally deodorant; they cover up mistakes in the code. Each time a comment is written to explain what the code is doing, the code should be re-written to be more clean and self explanatory. If you are unsure how to make it more clear, get help .(Hopefully you were already pairing. If not, this is an excellent execuse to get another pair of eyes.)

Comments are appropriate many times. For example, comments can be used to note areas of code that need refactoring, but for practical reasons are being left as is. They may warn against changes, as a section of code may have been tweaked for performance reaons and shouldn't be changed. (Or at least the decision to change it shouldn't be made lightly.) They can note design decisions and tradeoffs made.

For example, I recently had a situation where 6 different possible actions can be invoked depending on the state of the object. This screams polymorphism to me, but I decided it would be overkill, in this case. The specifics are not relevant, but I commented the source code to indicate this decision. If someone decides to refactor it later, so be it.

So, before you use a comment for explaining complicated code, please think about a way to improve the code.

Any intelligent fool can make things bigger, more complex, and more violent. It takes a touch of genius--and a lot of courage--to move in the opposite direction. --Albert Einstein

I have always believed in Einsten's quote. There is a related one:

Everything should be as simple as possible but not simpler.-Alber Einstein

The two quotes embody a basic software design philosophy that, when applied, results in good things: simple code is clear, maintainable, reusable, and extendable. But as Einstein notes, simplicity is hard.

This is is why Test Driven Development (TDD) is beautiful. When practiced with discipline, automated tests guide the programmer to simplicty; they provide a roadmap to nirvana. (Alright, this is a bit too flowery. I am starting to sound like an XP evangelist)

Achieving simplicty is still hard. But for software, TDD makes it a little easier.

Upon recent refelections of Agile Fusion and the corresponding forum discussions, I've had a couple of "aha" moments.

We have been asking the question, "What is the role of testers in XP?". Perhaps this is the wrong question. It is a little too general and implies its answer is prescriptive and would be a proclamation.

A better question might be "how can a tester contribute to an XP project?". A slight difference in wording has significant difference in implication. It is open ended; it is not prescriptive but exploratory. It is the type of thing Lisa Crispin addresses in her book.

Still, I think there is more to this. One element of XP that is appealing is its simplicity. Furthermore, I am amazed as to how many contexts can be "reduced" (one of the "aha" moments, see this post) so that XP is appropriate. But, XP doesn't address all areas of software development; XP is developer and code centric.

Metaphor, Simple Design, Automated Testing, Refactoring, Pair Programming, Collective Ownership, Continuous Integration and Coding Standards are directly about coding. The remaining practices (Planning Game, Small Releases, Onsite Customer and 40-hour Week) are about either staying out of the programmers way so they can code or improving communication about what they are going to code.

Anything that is outside the realm of "coding" is not really addressed by XP and I don't think we should try to change XP to address these other things. I think it would hurt more than help; it would complicate XP and is beyond XP's intention.

But, there are other agile practices that address these other concerns and work in harmony with XP. Scrum is the best example. Scrum is about project management, not coding. When I am asked about the role of project managers in XP, I suggest scrum. Scrum is another process that collaborates with XP; it doesn't really change or extend XP. I think this is a key reason developers don't have allergic reactions to scrum. It doesn't get in our way and we can pretty much ignore it.

But scrum is great for the customer and project manager; it helps deal with many of their concerns. So, I think we should consider what would be an agile process for testing, or rather figure out what is "agile testing".

I cringe a bit even as I type "agile testing", as there has been some disagreement already over its definition. Perhaps a different name will be better, but I am specifically looking for a process, framework or practice that adheres to the following guidlines:

• is consistent with the agile manifesto
• will complement, not impair, XP

I think there is enough experience among people like Brian Marick, Brett Pettichord, Lisa Crispin, James Bach, Andy Tinkham, Cem Kaner, Elisabeth Hendrickson, and others (sorry if I left anyone out), that if you were to mine your experience, you probably could come up with some ideas and patterns that would address the above. I think a lot of Brian's posts to his blog, are exploring this.

Part of the confusion for me has been the scope of testing. One dimension of testing is directly related to coding, and these facets can benefit from tester/programmer pairing. But so much of testing is not about coding, but exploring risk, for example. These "para-coding" activities and goals are outside the scope of XP, but could complement XP and therefore make for a more productive team and a successful project.

I frequently read and hear about claims that "XP won't work for us" or "I can't see how we could do XP". XP isn't appropriate for every development context, but it works in suprisingly more settings than it may first seem.

There is a mathematicl technique known as reductions that I think provides a nice metaphor for this problem. Reductions are a theorem proving technique, in which you convert an existing problem to another problem. The other problem, which is hopefully simpler, is now the one you provide the proof for and therefore show that the given solution can be extended to the original problem.

There are many contexts where people assume you can't use XP. But if you try to find a reduction for the context, you frequently can filter out a lot of noise and complexity, such that you can see how the context can be simplified and XP can be used.

If nothing else, the process of thinking about your context from a different perspective will probably expose assumptions and areas for improvement.

At Agile Fusion, Michael Feathers demonstrated a technique he learned from Ron Jefferies, that Ron called Ironman CRC. While at Agile Fusion, a few of us used the term Naked CRC, which I think is much better as it is more memorable and better describes the technique.

This is really hard to describe unfortunately. It is much easier to demonstrate. The idea is that you layout index cards, without anything written on them, as you describe basic collaborations of the system. The cards serve as a visual guide to your discussion. The key idea is that you only focus on a few classes / objects in the collaboration. Besides making the discussion easier to follow, using only a few classes allows people to follow the significance of the cards, as they have nothing written on them. I like this because it forces me to keep things simple when I use Naked CRC. If someone tells me "Wait, what kind of object is this card?", I realize that I have probably over complicated the example.

I have modified the technique to use multi-colored index cards. I bought a pack of index cards that came in four colors. (Incidentally, in college I learned about four color maps and how four colors is actually sufficient to draw any map without having any two adjacent entities be the same color. So, four colors works well with Naked CRC). I find the colors are easier for people to keep track of the model being shown, without resorting to writing on the cards and making things too complicated.