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.
MikeRand
  • 1,133
  • 8
  • 18

2 Answers2

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.

S.Lott
  • 45,522
  • 6
  • 93
  • 155
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.

Community
  • 1
Martin Wickman
  • 13,365