Even with XP, there's planning and design. I sure hope that would be documented before and after coding (when there are changes from the specs). The plan and design is more important to the layperson. Without it, it's simply hacking in the guise of XP. I wouldn't trust anyone to build my house without design and a plan detailed in documentation. Agreed. My earlier comments were more addressed to the notion of documenting only for the sake of documenting. Most useful design
Oh my. Do you expect the layperson to read your code? Consider a code snippet (the humble for_each) lifted from STL (from g++):
/** * @brief Apply a function to every element of a sequence. * @param first An input iterator. * @param last An input iterator. * @param f A unary function object. * @return @p f. * * Applies the function object @p f to each element in the range * @p [first,last). @p f must not modify the order of the sequence. * If @p f has a return value it is ignored. */ template<typename _InputIterator, typename _Function> _Function for_each(_InputIterator __first, _InputIterator __last, _Function __f) { // concept requirements __glibcxx_function_requires(_InputIteratorConcept<_InputIterator>) __glibcxx_requires_valid_range(__first, __last); for ( ; __first != __last; ++__first) __f(*__first); return __f; }
I would be thankful for the documentation written prior at the top. There's no such thing as self documenting code. I don't think BDD will even help in documenting the intent of the algorithm.
Give it a shot and see if you can capture the intent: "Applies the function object f to each element in the range[first,last). f must not modify the order of the sequence. If f has a return value it is ignored.". But you did do what I asked for! I never said that you can't have comments, though one's reliance on them should be as minimal as
Sorry, I'm behind; I didn't follow the thread over the weekend. Joel de Guzman wrote: processes result in useful documentation as a result of the design approach and are not written after the fact to fulfill some kind of procedures standard. The best approaches produces documentation almost as a necessary side effect. I generally ask individuals to write out their proposals and present them to one another and others to a level of detail necessary to convey to the involved stakeholders that each understands the other. Is it exhaustive in detail? No, not at all. Does it provide a framework and criteria for measuring successful results? Yes. They iterate and refactor on that just as they would the code. Such writing is their tool and platform for working out their approach and reaching agreement. As a result we end up documentation without having to do it after the fact or add more weight to the process. It may not be in a standard format or prove how every detail will work with certainty, but it does provide the essential 80% of what we do need to reasonably approach the problem. possible. In this example, you have variable names that convey their role (except "_f" might have been better as "_function") and I probably would have used braces and indentation for the inner single line for-loop. Style points to be sure, but ones that might allow a layperson to more easily grasp the code's intent. I think my point is one that we probably take as a best practice anyway: you do in the code what must be done so that next reader can understand what you were trying to do and why you did it. We often have to contend with other programmers, let alone laypersons, who would struggle to read the above code without documentation. Why not accept that and have the discipline to make it readable to a somewhat broader audience. Even so, I could reasonably get across the gist that this loops through everything passed to it and applies a given function. I'm not suggesting that we dumb code down and avoid language constructs, just that we don't make its meaning more obscure than necessary. I'm not suggesting that a layperson will follow the detailed nuance of it. But client code using the above code will now likely use a more readable for_each loop and the semantics are somewhat more clear to non-C++ readers. As I said in my earlier post, I'm not expecting 100% solvency here, just that we consider the code, with its test cases, a key part of the final documentation. Any documentation that attempts to restate the code after the fact will likely introduce translation errors and increase maintenance. Indeed, even the comments can suffer this, but at least they're inline where they can be considered at the same time. If we take care to have the code, especially at higher levels, clearly depict the logic for a wider audience, we can better assure that we're consistent with specs. Unfortunately, programmers are often too clever, writing something that never matches the problem statement in its construction and that has dubious performance improvements. Yes, it might be for that day, for that set of tests, they might have had results that matches results expected in the specification, but if it doesn't follow the same approach, how can we reasonably validate its side effects and bounds of performance? Instead you have a scenario where the sponsor asks did you do item A and the programmer nods yes and points at a couple of tests but really they did B or some variant of A that if the sponsor could read it would realize some essential point of departure that hadn't been thought of to measure in the tests.
Or maybe I've not correctly interpreted what you mean by "documentation is simply readable code". 1) Is the code above equally readable without the documentation at the top? 2) How would you capture the behavior of the algorithm with BDD?
As I said in my first post, I'm struggling my articulation of this notion and avoiding some realm of Colbert-ian truthiness given that I don't have any bright lines. But it seems to be a Good Thing if code can reflect the problem statement as close as possible and to be written in a way that reduces how arcane it is so that stakeholders can participate in its direct review.
The question is how BDD can help write code that clearly reflects the algorithms involved. Try the simple for_each, see if you can convince me. Then try a more elaborate algorithm, say, quicksort. See if you can capture the essence of the algorithm in BDD. I wasn't acting as a proponent or opponent of BDD as I'm not familiar with it, but would too invite those BDD proponents to respond.
My first post was in response to Rene Rivera's comment with regard to the dark days of laypersons coding. I agree with that sentiment (something about Shakespeare and monkeys comes to mind), but think that there is a middle road that would improve our practice. If I've distracted the thread, I apologize, but it seemed a good opportunity to let others beat on this straw-man I'm wrestling with. I very much appreciate your responding to my posts. Regards, Richard