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
  • 210 Views
  • 12 Minutes Discussion Span
  • Latest Post Latest Post by rproffitt
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.