How do I follow DRY when documenting module structure and interfaces?

Question

In this paper, it is recommended that one document the following:

module structure
module interfaces

If I'm writing detailed module structures and interfaces in a standalone document, aren't I repeating work that is also done with object declaration statements, unit tests, and docstrings?

If so, and if this is bad repetition in the DRY sense of the term, how do professional programmers avoid this kind of repetition?

Automatically generate tests/docstrings/code from documentation?
Automatically generate documentation from tests/docstrings/code?
Rely on the code as documentation and don't duplicate in the first place?
Suck it up, Nancy! It's called "work" for a reason.

Why do you care what that linked-to paper says? It looks 20 years old and *very* outdated. — quentin-starin, Apr 26 '11 at 21:46
Linked-to paper was recommended in another SO post. And I've enjoyed very much all of the Parnas I've read. — MikeRand, Apr 26 '11 at 22:12

score 4 · Accepted Answer · answered Apr 26 '11 at 20:31

4

Automatically generate documentation from tests/docstrings/code

Correct.

Find a tool that fits your language and creates documentation from comments embedded in the code.

answered Apr 26 '11 at 20:31

S.Lott

45,264
6
90
154

a tool.. such as? – gbjbaanb Apr 26 '11 at 20:46
@gbjbaanb: Since there's no language on the question, it's hard to name a tool. However, tools that build documentation from comments are very, very common. Pick a language, and then it's easy to google for tool. With no specific language it's impossible to suggest a tool. – S.Lott Apr 26 '11 at 20:59
Python = sphinx? I noticed that's what you used for your books (and Python uses for their docs). Or were you thinking of something more API-centric like epydoc? – MikeRand Apr 26 '11 at 21:28
@MikeRand: If you're programming in Python, Sphinx is a good way to generate documentation from code. For C++ or Java, there are other tools. I'm not familiar with all the languages in common use, but if you were to name a specific language, a tool to extract documentation from that language is likely to exist. – S.Lott Apr 26 '11 at 22:03

score 2 · Answer 2 · edited Apr 12 '17 at 07:31

2

Yes, you are repeating yourself if your documentation is just a simple rehash of the code.

I've seen enough of this in my days to last a lifetime:

/**
 * Set the name
 * @param name The name
 */
void setName (String name) { ... }

It is madness!

Instead of the above, leave obvious code to speak for itself and focus on finding areas in your code which is hard to understand and then rewrite those parts so comments are unnecessary. If you still cannot express the intent with code only, try again. Focus on the why and not how.

I'm a huge proponent of readable code.

edited Apr 12 '17 at 07:31

Community

1

answered Apr 26 '11 at 20:37

Martin Wickman

13,305
3
31
66

Even more madness: Usually, the people who write (or let eclipse generate) such comments are really proud about their javadoc code coverage of >95%... – blubb Apr 26 '11 at 20:41
It may be madness, but generating additional documentation separate from the code is even worse. The question is not "what's been done badly in the past?" The question is "what do you recommend we do?" This answer seems sort of negative -- it identifies a bad practice, but doesn't seem to explain how to do it right. – S.Lott Apr 26 '11 at 20:59
@S.Lott Thanks, good point. Added a blurb about that. – Martin Wickman Apr 26 '11 at 21:12

How do I follow DRY when documenting module structure and interfaces?

2 Answers2