Don’t just write comments, tell a story | Hacker News Reader

Don’t just write comments, tell a story

shahriarhaque.com

36 pointsshahriarhaque16 comments

Otherwise 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.

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.

It might be worth it, but the best code I ever wrote had 0 comments, it didn't need it...

"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.

I agree that "Why" comments are infrequent, but they are still important. I work in the scientific computing field and here "whys" are they key to understanding code. But lengthy explanations of why certain steps of the algorithm are needed, are very distracting. Such a scenario calls for a separation of code from comments.

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 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.

Well put. The same goes for comments, too. Someone else asserted that good comments should reflect "Why" more than "What". "What" changes more.

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 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.

When you start your source file with a huge chunk of "how" comments it is likely to not match the actual code path. But that's not how I think the "documentation mode" will work. You write how comments for every small chunk of code. Then whichever code path the program executes, you will see a flow of comments from that path

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 :)

Did you see doctest? (http://docs.python.org/library/doctest.html)

I think this could be another brilliant addition to the "documentation view". Imagine a multi-tabbed documentation pane. The first tab lets you write normal comments, but in another one you could write doctests like the example you gave, or even assertion of pre and post conditions.

   Scenario:
   First I had a problem
   Then I thought, "I know, I'll use BDD"
   Then I had two problems

Docco is cool. Is there an online version of it, to give it a try?

Reply on news.ycombinator.com