11–18 of 18 posts
I think that's really cool! Next step: parse those stories using a BDD framework! Looking at that interface brings to mind something like lettuce.it You could parse out the comments into a separate story block then write in the features/notes from lettuce and have them link back to each chunk of the code - providing coverage reports and the like. Now it just needs a vim plugin ;)
Scenario:
First I had a problem
Then I thought, "I know, I'll use BDD"
Then I had two problemsEarlier quoted context omitted.
I completely disagree. When code changes rapidly, and especially when multiple people are working on the same code, documentation which explains the "why" of the code is very valuable. Without it, you're left trying to figure out if some piece of code is really necessary, or still necessary. If you're lucky you can rum 'blame' and figure out who wrote the bit in question and go talk with them about it. If you're unlu…
I agree with this response. This is the same argument as for unit testing. When your code changes, you have to maintain your tests, too, sometimes throwing them out with the deleted code. In other words, for any code change, you could have a test and a comment. And that is part of the job. The job is not just "write code". It is "write maintainable, bug free code".
I know teams that have an "every change should break some unit test" policy, and IMNSHO those teams are making way more work for themselves than they need to. The point of tests is not to make sure that the code does what it does, the point is to make sure that it does what you need it to.
Earlier quoted context omitted.
I agree with this response. This is the same argument as for unit testing. When your code changes, you have to maintain your tests, too, sometimes throwing them out with the deleted code. In other words, for any code change, you could have a test and a comment. And that is part of the job. The job is not just "write code". It is "write maintainable, bug free code".
The point of unit tests is to provide an executable specification. Ideally, the specification changes less frequently than the code does. In practice, the specification tends to change a lot too, but you should be able to perform optimizations or refactorings without having to change a whole lot of unit tests. I know teams that have an "every change should break some unit test" policy, and IMNSHO those teams are maki…
I think that's really cool! Next step: parse those stories using a BDD framework! Looking at that interface brings to mind something like lettuce.it You could parse out the comments into a separate story block then write in the features/notes from lettuce and have them link back to each chunk of the code - providing coverage reports and the like. Now it just needs a vim plugin ;)
Whoever eventually figures out the obvious-yet-hidden confluence between cucumber-style BDD 'stories' and javadoc-style documentation is going to make a big splash in the word of programming. I can only hope it's me :)
Earlier quoted context omitted.
I completely disagree. When code changes rapidly, and especially when multiple people are working on the same code, documentation which explains the "why" of the code is very valuable. Without it, you're left trying to figure out if some piece of code is really necessary, or still necessary. If you're lucky you can rum 'blame' and figure out who wrote the bit in question and go talk with them about it. If you're unlu…
"Why" comments are often quite useful, but the example in the article was filled with "What" comments, and doesn't seem to be talking about that at all. "Why" comments are often infrequent enough that there's nothing wrong with putting them inline with the code.
Narratives in code are a tempting analogy, but code is non-linear. Verbose 'how' code comments usually assume one path through the code, and it only matches my actual path 0.1% of the time. The remaining 999 times out of 1000 all the verbosity just gets in the way. The best idea to come out of literate programming, IMO: order code in the best possible order for reading and navigating, and let the computer figure out…
Earlier quoted context omitted.
Whoever eventually figures out the obvious-yet-hidden confluence between cucumber-style BDD 'stories' and javadoc-style documentation is going to make a big splash in the word of programming. I can only hope it's me :)
Did you see doctest? ( http://docs.python.org/library/doctest.html )