This post originated from an RSS feed registered with .NET Buzz by Sam Gentile. Original Post: CodeAsDocumentation Feed Title: Sam Gentile's Blog Feed URL: http://samgentile.com/blog/Rss.aspx Feed Description: .NET and Software Development from an experienced perspective - .NET/CLR, Rotor, Interop, MC+/C++, COM+, ES, Mac OS X, Extreme Programming and More! Latest .NET Buzz Posts Latest .NET Buzz Posts by Sam Gentile Latest Posts From Sam Gentile's Blog

When I was on Ward's Wiki in 1996-2000 (something Ward personally thanked me for Thursday as he took me out to lunch) and we were coming up with would become XP, this was one of my huge hangups that took me a while to get right. As Martin says “Almost immediately I feel the need to rebut a common misunderstanding. Such a principle is not saying that code is the only documentation. Although I've often heard this said of Extreme Programming - I've never heard the leaders of the Extreme Programming movement say this. Usually there is a need for further documentation to act as a supplement to the code.”  Misconception #1.

Then, “The rationale for the code being the primary source of documentation is that it is the only one that is sufficiently detailed and precise to act in that role - a point made so eloquently by Jack Reeves's famous essay "What is Design?" This principle comes with a important consequence - that it's important that programmers put in the effort to make sure that this code is clear and readable.” So that's the thing. This practice ONLY makes sense in the context of other XP practices Refactor Mercilessly and Unit Tests. The only way the CodeAsDocumentation works is if you keep your code clean and concise so it is easier to understand, modify, and extend. Make sure everything is expressed once and only once. Then constantly test to make sure you didn't break anything. This keeps you code clean, readable and nimble.