5 Replies - 751 Views - Last Post: 23 September 2013 - 09:18 AM

#1 NecroWinter  Icon User is offline

  • D.I.C Regular

Reputation: 35
  • View blog
  • Posts: 318
  • Joined: 21-October 11

Documentation

Posted 23 September 2013 - 07:37 AM

Just wondering how you guys document your projects and code? I've had a class on it, but I would like examples from people in the "real world"

thanks
Is This A Good Question/Topic? 0
  • +

Replies To: Documentation

#2 Skydiver  Icon User is online

  • Code herder
  • member icon

Reputation: 3548
  • View blog
  • Posts: 10,989
  • Joined: 05-May 12

Re: Documentation

Posted 23 September 2013 - 08:09 AM

Self-documenting code. Minimal comments. To paraphrase another forum luminary here "I consider it a failure if I have to write a comment because I couldn't write the code clearly enough to not need the comment."
Was This Post Helpful? 0
  • +
  • -

#3 BetaWar  Icon User is offline

  • #include "soul.h"
  • member icon

Reputation: 1147
  • View blog
  • Posts: 7,134
  • Joined: 07-September 06

Re: Documentation

Posted 23 September 2013 - 08:16 AM

This can get into a religious war, but the way I document my code is through the following:
1. Understandable variable names which are named logically (descriptive, but concise, for the variable's use).
2. Comments! That is right, I comment each and every function that I write (at least at the top of the function, in the header file). I also use doxygen or similar (JavaDoc in Java, etc.) to generate documentation from the code comments.
3. There is no 3 :)

Basically, I just write comments to doxygen format and then have doxygen do the documentation generation for me. Makes things easier.
Was This Post Helpful? 1
  • +
  • -

#4 Skydiver  Icon User is online

  • Code herder
  • member icon

Reputation: 3548
  • View blog
  • Posts: 10,989
  • Joined: 05-May 12

Re: Documentation

Posted 23 September 2013 - 08:22 AM

There is the older thread that may give you some insight.
Was This Post Helpful? 0
  • +
  • -

#5 Ryano121  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 1362
  • Posts: 3,002
  • Joined: 30-January 11

Re: Documentation

Posted 23 September 2013 - 08:31 AM

Also it's good idea to get into the habit of trying to document your code whilst you write it. It's not a good feeling when you've written a mass of code without any kind of documentation at all and you then have to go through it all later on and document the whole thing at once (extremely dull work).
Was This Post Helpful? 0
  • +
  • -

#6 Skydiver  Icon User is online

  • Code herder
  • member icon

Reputation: 3548
  • View blog
  • Posts: 10,989
  • Joined: 05-May 12

Re: Documentation

Posted 23 September 2013 - 09:18 AM

Whereas code is where the rubber meets the road and I go for minimal documentation, I also ascribe to lean and DRY documentation on the user stories, requirements, specifications, and design documents side of things. If at all possible, a wiki would be ideal (as much as it sucks when trying to actually print out documents). I like the idea of using a wiki because you can link the individual user stories, individual requirements, specification items, and design diagrams together. There is no need to re-type the same information over and over again when you go from course to fine grain. Readers can decide the dive into elements if they wish, or stay at the level of information that they need if don't. Whenever possible, prefer to use UML diagrams instead of text. The only reason why I'm not fulling pushing wiki's is because I still haven't found a great solution for sticking in UML diagrams in wikis and have an easy workflow whenever an edit needs to happen.

Whatever happens, version control is a must for these documents. You'll want to keep track of which version a spec is at when a design decision is made. Additionally, project schedules should also be version controlled to keep track of when management and/or marketing has started taking the good drugs and didn't share.

I'm still on the fence about test plans, tests, bugs, and UAT results. I feel that test plans should also live within the same wiki, but tests, bugs and UAT results should live in a database.

It would be interesting see what people think about this other end of the spectrum for software documentation.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1