6 Replies - 1172 Views - Last Post: 10 January 2010 - 04:00 PM

#1 Nic30n3  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 20
  • Joined: 26-March 09

Documenting Source Code

Post icon  Posted 09 January 2010 - 01:30 PM

What are good formats for a document documenting the source code. What is the Software Dev Industry standard? Does anyone know or know of any good example of documenting the source code?

Like documenting the code conventions, file structures, the program flow, and what the code does and things like that?
Is This A Good Question/Topic? 0
  • +

Replies To: Documenting Source Code

#2 Martyr2  Icon User is offline

  • Programming Theoretician
  • member icon

Reputation: 4189
  • View blog
  • Posts: 11,863
  • Joined: 18-April 07

Re: Documenting Source Code

Posted 09 January 2010 - 02:10 PM

Read the book Code Complete 2 by Steve McConnell. He covers a lot of conventions you can adopt in your own style. There is no real "industry standard" but each company typically has their own standard from everything about commenting to variable naming notation.

Ideally with comments you want enough to explain the flow of your code, but not enough to get in the way of someone reading your statements. I typically have a nice little header at the top telling what the code file does, when it was last updated and its purpose. Then I follow through the code with simple one liners that describe *important* steps about what it is doing. Typically this means I have 2-5 lines per function that describe expected inputs and outputs or critical formulas.

But again, everyone has their own style and you will quickly see in the industry each company has their own set of standards to keep everyone on the same page. :)

This post has been edited by Martyr2: 09 January 2010 - 02:11 PM

Was This Post Helpful? 0
  • +
  • -

#3 KYA  Icon User is offline

  • g++ jameson.cpp -o beverage
  • member icon

Reputation: 3089
  • View blog
  • Posts: 19,137
  • Joined: 14-September 07

Re: Documenting Source Code

Posted 09 January 2010 - 03:02 PM

I'm all about self documentation. If I've named my variables/functions well, the only thing for any comments to do is to explain the 'why', since the code covers the 'how' by itself.
Was This Post Helpful? 0
  • +
  • -

#4 dorknexus  Icon User is offline

  • or something bad...real bad.
  • member icon

Reputation: 1255
  • View blog
  • Posts: 4,618
  • Joined: 02-May 04

Re: Documenting Source Code

Posted 09 January 2010 - 03:32 PM

most software projects will utilize document generating systems to aid in the usually tedious task of documenting source code. The one I am most familiar with is doxygen (http://www.stack.nl/~dimitri/doxygen/). I am used to the JavaDoc format which is also fairly readable in raw source form. There is a section on the Doxygen site which talks about how to markup code for the document generators: http://www.stack.nl/.../docblocks.html

This post has been edited by Dark_Nexus: 09 January 2010 - 03:33 PM

Was This Post Helpful? 0
  • +
  • -

#5 Tom9729  Icon User is offline

  • Segmentation fault
  • member icon

Reputation: 180
  • View blog
  • Posts: 2,641
  • Joined: 30-December 07

Re: Documenting Source Code

Posted 09 January 2010 - 06:29 PM

My main programming languages are C and Java, so I generally use Doxygen syntax because it is largely the same as Javadoc syntax.

The below snippet is C code, but you could write a similar function in Java with the same comment and it would be acceptable for Javadoc.

/**
 * Add two integers.
 * 
 * @param x The first integer.
 * @param y The second integer.
 * @return The sum (x + y).
 */
int foo(int x, int y);



Doxygen also has some commands that let you include images, examples, etc into the generated API docs. By default it generates HTML docs, but it can do a lot of other formats as well.

Example: API docs for my game library, generated from the sourcecode with Doxygen.
Was This Post Helpful? 0
  • +
  • -

#6 Nic30n3  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 20
  • Joined: 26-March 09

Re: Documenting Source Code

Posted 10 January 2010 - 03:58 PM

View PostTom9729, on 9 Jan, 2010 - 05:29 PM, said:

My main programming languages are C and Java, so I generally use Doxygen syntax because it is largely the same as Javadoc syntax.

The below snippet is C code, but you could write a similar function in Java with the same comment and it would be acceptable for Javadoc.

/**
 * Add two integers.
 * 
 * @param x The first integer.
 * @param y The second integer.
 * @return The sum (x + y).
 */
int foo(int x, int y);



Doxygen also has some commands that let you include images, examples, etc into the generated API docs. By default it generates HTML docs, but it can do a lot of other formats as well.

Example: API docs for my game library, generated from the sourcecode with Doxygen.


What if the code does not have any comments in it? Can Doxygen genarate any documentation for it?
Was This Post Helpful? 0
  • +
  • -

#7 Tom9729  Icon User is offline

  • Segmentation fault
  • member icon

Reputation: 180
  • View blog
  • Posts: 2,641
  • Joined: 30-December 07

Re: Documenting Source Code

Posted 10 January 2010 - 04:00 PM

View PostNic30n3, on 10 Jan, 2010 - 05:58 PM, said:

What if the code does not have any comments in it? Can Doxygen genarate any documentation for it?

No.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1