

Don’t just write comments, tell a story - shahriarhaque
http://shahriarhaque.com/blog/?p=83

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

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

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

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

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

~~~
shahriarhaque
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

------
dools
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 ;)

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

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

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

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

