Member Avatar for RikTelner

Assume you guys are done with your professional projects.
Do you write explanation of working of your projects in the comments in the code.
Or do you write entire documentation addressing every variable and function?
Or do you do both?

If you do both, how do you avoid repeating yourself? After all you're writing the same.
If you do either, what are some good examples or thoughts you would share with a newbie who does documentation for first time? I can make it look clean and easily see-through. But beside that?

Edited by RikTelner
  • 2 Contributors
  • 1 Reply
  • 218 Views
  • 12 Minutes Discussion Span
  • Latest Post Latest Post by rproffitt

Dani AI

Generated

Short answer: both, but each for a different audience. raised the right question about duplication; 's reminder to follow client needs and to start from a user-focused manual is also practical. Treat inline comments as a place for implementation intent and surprises, and external docs as the canonical, user- and maintainer-facing contract.

A compact, repeatable structure that ages well:

  • README / Quickstart: what it is, how to run, one runnable example.
  • API reference (auto-generated from docstrings): what each public function/class does, inputs, outputs, errors.
  • Design notes / ADRs: why major decisions were made and alternatives considered.
  • Tests and examples: living documentation that proves examples work.
  • Inline comments: explain why a non-obvious choice was made or note tricky edge cases; avoid restating the code.

Practical workflow to avoid duplication: write public docstrings first for the exported surface, generate reference docs automatically, and keep higher-level usage guides in Markdown. Use example code as tests (doctest or runnable snippets) so CI fails when examples break. Add a lightweight doc-check in CI (link checks, example execution, or documentation build) so documentation drift is caught early.

Two fast rules for maintainable docs: comments explain intent, not the literal code, and documentation changes are part of any feature change estimate (echoing on client expectations). When documentation must be exhaustive, budget it like any deliverable and prefer single sources of truth (docstrings + generated API pages) to minimise manual repetition.

Member Avatar for rproffitt

Before I answer, you haven't asked a new question as we read from https://www.google.com/search?q=Documentation+or+in-code+comments&ie=utf-8&oe=utf-8

So my answer is that you do what the person is paying you to do. Heresy!

And the higher you up SEI, CMM and so on, the less you see of the code. As you move to a system like SEI Level 5, you put in a change request and that generates the code. Example? The Space Shuttle was SEI Level 5 with an exception for the backup computer. To some this never really happened and some will write "Burn the witch!" over use of such magic.

What I find is I have to use a variable approach to each project. I'll do what the client demands even if I disagree. They are paying the bills so let's give them what they want.

So what do I use? I think I like a method I read in "The HP Way" years ago. We produce The User's Manual first. This describes what it does and how the user uses it. Now we have a fine end goal and can map out how to get there. There are thoughts that you document the code before you write code but my view is you do that if paid well and they accept the years it will take.

This reply is pretty much a chip off the visible ice berg of the question you posed.

Edited by rproffitt because: Needed to clarify
Be a part of the DaniWeb community

We're a friendly, industry-focused community of developers, IT pros, digital marketers, and technology enthusiasts meeting, networking, learning, and sharing knowledge.