It is hard to convince people that XP works. For example, ExtremeProgrammer's believe that ExtremelyClearCode is much better than mediocre code with comments. Some people believe that self explaining code cannot exist. Code must have comments and if it doesn't, well that's just plain hackery. I think this is because they have never seen ExtremelyClearCode. So let's try to put a couple of examples online.

If you have the source code for an ExtremeProgrammingProject online, please include a link here:

	*http://www.wi.leidenuniv.nl/~mmeijeri	This is only an attempt at XP. Please tell me what's wrong with it and I'll try to fix it.	

----

I posted this example to comp.software-eng. --EricUlevik

Add comments to make the code understandable. Then review your code, and rewrite it to make it understandable without the comments. Then add mandatory comments (eg. copyright).

Generally, comments are a sign of code that needs more work. 

An example of good C commenting from "Code Complete", page 480: 

 /* copy input field up to comma */ 
 while (*InputStr != ',' && *InputStr != END_OF_STRING) {
   *Field = *InputStr; 
   Field++; 
   InputStr++;
 } /* while -- copy input field */

 *Field = END_OF_STRING; 

Hideous. This code needs reworking. If the loop deserves two comments, it definitely deserved to be placed in a separate function. So one way of fixing these comments is:


 void copy_until_char(char* out, char* in, char c)
 {
   while (*in && *in != c) 
     *out++ = *in++; 
   *out = 0;
 }

 copy_until_char(Field, InputStr, ','); 

But it seems silly to be writing all this code for an operation so common, so we look up the C manual and instead write:

 char* comma;
 strcpy(Field, InputStr);
 if (comma = strchr(Field, ','))
   *comma = 0; 

which finally seems somewhat readable without comments. Try reading it out loud: "copy the string, search for a comma, if it's found end the string there". And, because it uses the standard library, it will most likely be smaller and faster than the previous versions.
----
That's all well and good, but I can't help worrying about performing such transformations in isolation.  The semantics have slightly changed between the original and final versions.  If there isn't enough room in the destination buffer for more than ''exactly'' the right number of characters (a common occurrence in memory-limited C programs) then the final version can introduce horrible memory-corruption problems as it continues to copy after the comma.

How about:

 strcpy(Field, strtok(InputStr,","));

or, if you worry about the robustness of strtok (and it has some well known problems), how about:

 int len = strcspn(InputStr, ",");
 strncpy(Field, InputStr, len);
 Field[len] = 0;

Remember. The standard C library is your friend.

-- FrankCarver
----
As pointed out by the previous author it is important when refactoring to code to make it more readable that 
you refactor it to code that is both correct & clear. I still however think the code NEEDS coments.

 /* copy characters up to but excluding the first ',' */  <<<< Comment is user domain english
 int len = strcspn(InputStr, ",");
 if (len <= maxlen) {
   strncpy(Field, InputStr, len);
   Field[len] = 0;
 } else {
   /* string to long Error */
   .....
 }

Why the comments ?
Because when you accidently do this

 /* copy characters up to but excluding the first ',' */ 
 char* comma;
 strcpy(Field, InputStr);
 if (comma = strchr(Field, ','))
   *comma = 0; 

The people know what algorithm you were trying to implement.
Also when the comment contradicts the code we know to trust neither!
If I just see this code alone I am not sure if all those chars in Field that come after the '\0'
are really needed.
----
But remember, none of the XP practices are done in isolation.  Normally, you might have a point about trusting neither comments nor node, but in full-on xp, we'd have a set of ''authoritative'' unit tests, which should make our intent clear:  'assertEquals("Blah" , testedCode("Blah, ha, ta"));' is quite unambiguous. -- WilliamUnderwood
----
CategoryExtremeProgramming | CategoryExtremeProgrammingExamples