4

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.
Improve this question
2
  • Why do you care what that linked-to paper says? It looks 20 years old and very outdated. Commented Apr 26, 2011 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. Commented Apr 26, 2011 at 22:12

2 Answers 2

Reset to default
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.

Improve this answer
4
  • a tool.. such as? Commented Apr 26, 2011 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. Commented Apr 26, 2011 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? Commented Apr 26, 2011 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. Commented Apr 26, 2011 at 22:03
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.

Improve this answer
3
  • Even more madness: Usually, the people who write (or let eclipse generate) such comments are really proud about their javadoc code coverage of >95%... Commented Apr 26, 2011 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. Commented Apr 26, 2011 at 20:59
  • @S.Lott Thanks, good point. Added a blurb about that. Commented Apr 26, 2011 at 21:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.