Don’t just write comments, tell a story
shahriarhaque.com
Don’t just write comments, tell a story
1–10 of 18 posts
Re: Don’t just write comments, tell a story
#2[deleted]
Re: Don’t just write comments, tell a story
#3I 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 ;)
Re: Don’t just write comments, tell a story
#4Otherwise known as Literate Programming with an IDE. :-)
The general problem with this is that code changes too rapidly for documentation to be of any use. Writing the documentation for code can easily take 2-3 times longer than writing the code itself, so if you're iterating at all, that documentation will probably be about 5 revisions out of date. At that point, it's actively harmful, because it tells the reader things that are wrong.
It works great for TeX, not so well for a startup that will have a new business plan in a couple months. That's also why the best comments tend to be API docs: APIs change (or should change) much less rapidly than implementation, so the documentation is both more useful and has less chance of being out-of-date.
Re: Don’t just write comments, tell a story
#5Otherwise known as Literate Programming with an IDE. :-) The general problem with this is that code changes too rapidly for documentation to be of any use. Writing the documentation for code can easily take 2-3 times longer than writing the code itself, so if you're iterating at all, that documentation will probably be about 5 revisions out of date. At that point, it's actively harmful, because it tells the reader th…
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 unlucky, they don't work there any more. Either way, it's more time consuming that reading a good code comment about why something is being done.
Is there a cost to writing good comments? Yes. Does it take discipline to keep them up-to-date and accurate? Yes. Is it worth it? Yes.
Re: Don’t just write comments, tell a story
#6I 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 :)
Re: Don’t just write comments, tell a story
#7Otherwise known as Literate Programming with an IDE. :-) The general problem with this is that code changes too rapidly for documentation to be of any use. Writing the documentation for code can easily take 2-3 times longer than writing the code itself, so if you're iterating at all, that documentation will probably be about 5 revisions out of date. At that point, it's actively harmful, because it tells the reader th…
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…
It might be worth it, but the best code I ever wrote had 0 comments, it didn't need it...
Re: Don’t just write comments, tell a story
#8Otherwise known as Literate Programming with an IDE. :-) The general problem with this is that code changes too rapidly for documentation to be of any use. Writing the documentation for code can easily take 2-3 times longer than writing the code itself, so if you're iterating at all, that documentation will probably be about 5 revisions out of date. At that point, it's actively harmful, because it tells the reader th…
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.
Re: Don’t just write comments, tell a story
#9Narratives 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 how to compile it. That's one thing we've largely gained from more dynamic languages like python and ruby, and from AOP. That's about it. It's good to to aim for a codebase I can curl up with on my iPad, but if so my interest is in the code. Don't get hung up on typography, and assume I'm going to be choosing my own adventure at the end of each page.
Re: Don’t just write comments, tell a story
#10Otherwise known as Literate Programming with an IDE. :-) The general problem with this is that code changes too rapidly for documentation to be of any use. Writing the documentation for code can easily take 2-3 times longer than writing the code itself, so if you're iterating at all, that documentation will probably be about 5 revisions out of date. At that point, it's actively harmful, because it tells the reader th…
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".