🔒 Locked

Documenting programs

Started by benjamin bunny Apr 15, 2002 at 6:53 PM 26 replies 700+ views

Original Post

144

Apr 15, 2002 at 6:53 PM

I''ve just finished a Very Simple Computer simulator for an ASM project at uni. It was actually a pretty fun project to work on, but now I''ve got to write the specification, design and implementation for the program. (I was probably supposed to write the specification and design before I started coding, but I tend to find writing code is the best way to design a program.) Documenting code it isn''t something I''m very used to doing, so I figured it was about time I learnt to do it properly. Does anyone know of good web sites on documenting programs? I already googled, but didn''t find anything useful. ____________________________________________________________ www.elf-stone.com

Alamo

Apr 15, 2002 at 7:17 PM

asm? every instruction... document it... twice =P

benjamin bunny

Author

144

benjamin bunny

Apr 15, 2002 at 7:36 PM

I wrote it in Java, although I did write some simple ASM programs to run on it. Writing the whole thing in ASM might have been fun... it was 2500 lines just in Java.

____________________________________________________________
www.elf-stone.com

krikkit

Apr 15, 2002 at 10:51 PM

The opinion I have heard which I tend to agree with goes along the lines of "if you make it past 3 lines without commenting, you''ve missed something that could use explaining."
Believe me, when you are working with other people, nothing makes the next guy(the guy who''s going to implement or audit your code) happier than code that he couldnt be confused about if he tried.

dwarfsoft

247

dwarfsoft

Apr 15, 2002 at 11:31 PM

Uh, commenting sux0rs... Your code should be readable by any intelligent person

Just comment above each function telling what it is supposed to do, and any known bugs

Maybe put some comments in the code where you know it could go fubar at any point in time

-Chris Bennett of Dwarfsoft - The future of RPGs

GPA

Thanks to all the goblins in the GDCorner niche

benjamin bunny

Author

144

benjamin bunny

Apr 15, 2002 at 11:37 PM

Oh, I commented the code. I just need to write the design and specification document for it.

____________________________________________________________
www.elf-stone.com

KalvinB

Apr 15, 2002 at 11:42 PM

Just print out two copies of the source. Label one "Design Specs"

Ben

IcarusIndie.com

[The Rabbit Hole | The Labyrinth | Programming | Gang Wars | The Wall]

benjamin bunny

Author

144

benjamin bunny

Apr 15, 2002 at 11:47 PM

____________________________________________________________
www.elf-stone.com

Gabriel Fleseriu

Apr 16, 2002 at 1:43 AM

The design specifications I had to write always answered questions starting with "what" or "how many" and never questions starting with "how". This might help you decide what to write in there.

Forever trusting who we are
And nothing else matters - Metallica

Beer Hunter

122

Beer Hunter

Apr 16, 2002 at 7:07 AM

quote:
Original post by krikkit
"if you make it past 3 lines without commenting, you''ve missed something that could use explaining."

If your code really needs that many comments, you should spend more time making your code self-documenting. By using so many comments, you''re making it harder to see the code amongst all the comments, and slowing down anyone trying to read it.

Consider this example. Can you really add any comments that make it clearer?

  
bool is_prime(int num) {
  for(int i = 2; i <= sqrt(num); ++i) {
    if(num % i == 0) return false;
  }
  return true;
}

In general, I only describe the purpose of blocks of code, and only if the purpose isn''t obvious.

krikkit

Apr 16, 2002 at 7:44 AM

Rules of common sense do apply.

Arild Fines

138

Arild Fines

Apr 16, 2002 at 8:17 AM

quote:
Original post by Beer Hunter
By using so many comments, you're making it harder to see the code amongst all the comments, and slowing down anyone trying to read it.

Ever heard of syntax highlighting?

[edited by - Arild Fines on April 16, 2002 9:18:32 AM]

benjamin bunny

Author

144

benjamin bunny

Apr 16, 2002 at 8:38 AM

Its true. Too many comments can make code unreadable. I only ever comment every three lines or so when I''m writing something for Uni, then because I can''t guarantee the person reading it has a brain. If something''s obvious, why waste valuable time describing it? Its a bad habit IMO.

____________________________________________________________
www.elf-stone.com

dwarfsoft

247

dwarfsoft

Apr 16, 2002 at 9:16 AM

Your the first person with the same opinion as me. Commenting within code is a bad habit.

In any case, a function that is fubar will need to be writen from scratch to be fixed properly, so why comment your code? Nobody should be fixing it? they should be replacing it!

Functions should be relatively short, and if they are getting long, then maybe you need to slice a bit of it into a slightly smaller function...

That way everything stays small and managable, and replacing a function becomes an easy task...

UNI, however, forces you to write excessive functions (like one per line almost) and most of the markers are total dumbarses, which explains why they don''t have a REAL job outside of teaching

. Although the cleaner your code is written, the less comments you need to make (ie, only commenting the function of if statements, and loops, and occasionally explaining what a variable will be used for [if it isn''t an int i;

] ) ...

I got 100% for my last assignment that I provided about 1/3 of the commenting as my peers. It is true that meaningful comments allow understandability, I believe they commented because they felt they had to....

-Chris Bennett of Dwarfsoft - The future of RPGs

GPA

Thanks to all the goblins in the GDCorner niche

STVOY

Apr 16, 2002 at 9:55 AM

Well Now,

My Lecturer always tells us that never comment things such as simple syntax like cout printf etc. or calculations. Also for a small function just give one line saying what it does. If another coder takes over he can read the syntax and calculations. All he needs to know is what those blocks of code are intended to do by you (not what they look like they do). And how you have structured it. Besides everything else they need to know can be put in some other document accompanying the code. I did write an article on this some time ago at gamedeveloper.net but it''s old now and needs re-ramping and seriously addding too...

STVOY

Pyre Light Studios (Under Construction)

Beer Hunter

122

Beer Hunter

Apr 16, 2002 at 8:10 PM

quote:
Original post by Arild Fines
Ever heard of syntax highlighting?

  
// perform an insertion sort from a[low] to a[high]

void insertion_sort(int *a, int low, int high) {
  // temporary variable and two indicies

  int t, i, j;
  // loop through the array forwards

  for(i = low + 1; i <= high; ++i) {
    // record the current value

    t = a[i];
    // find the insertion point

    // loop through array backwards

    for(j = i - 1; j >= low && a[j] > t; --j) {
      // if insertion point not found, slide elements upwards

      a[j+1] = a[j];
    } // for(j = ...

    // insert the element

    a[j+1] = t;
  } // for(i = ...

} // insertion_sort

See my point?

dwarfsoft

247

dwarfsoft

Apr 17, 2002 at 10:10 AM

I doubt anybody would miss the point with that example. Commenting too much seriously hinders a project and you would spend most of your time trying to think of an apt but unrepetitive line to say "create three temporary variables for counting called i,j, and k"

-Chris Bennett of Dwarfsoft - The future of RPGs

GPA

Thanks to all the goblins in the GDCorner niche

Thrump

Apr 17, 2002 at 11:01 AM

quote:
Original post by dwarfsoft
Commenting within code is a bad habit.

A necessary bad habit though. In a perfect world, everybody would write beautiful self-explaining code from day 1. But, I''ve been programming for 4 years and I don''t think I''m at that point yet, even though I''m making a serious effort to become a better coder/designer.

Michalson

177

Michalson

Apr 17, 2002 at 11:05 AM

quote:
Original post by Beer Hunter
[quote]Original post by Arild Fines
Ever heard of syntax highlighting?

    
// perform an insertion sort from a[low] to a[high]

void insertion_sort(int *a, int low, int high) {
  // temporary variable and two indicies

  int t, i, j;
  // loop through the array forwards

  for(i = low + 1; i <= high; ++i) {
    // record the current value

    t = a[i];
    // find the insertion point

    // loop through array backwards

    for(j = i - 1; j >= low && a[j] > t; --j) {
      // if insertion point not found, slide elements upwards

      a[j+1] = a[j];
    } // for(j = ...

    // insert the element

    a[j+1] = t;
  } // for(i = ...

} // insertion_sort

See my point?

No, I don''t. If it wheren''t for the tabbing I wouldn''t have a chance of seeing where the inner loop ends. If you need to comment this way then you have a much bigger problem with poor variable naming/poor design.

dwarfsoft

247

dwarfsoft

Apr 17, 2002 at 11:21 AM

quote:
Original post by Thrump
A necessary bad habit though. In a perfect world, everybody would write beautiful self-explaining code from day 1. But, I''ve been programming for 4 years and I don''t think I''m at that point yet, even though I''m making a serious effort to become a better coder/designer.

Uh, it was a joke

.. I couldn''t function without at least minimal comment spattering through my code

... how could I possibly remember where I applied that last bugfix, or where the code lets the program get fubar? And how could I ever remember why I defined a variable called "f00" and another called "b4r" and what their purpose was

-Chris Bennett of Dwarfsoft - The future of RPGs

GPA

Thanks to all the goblins in the GDCorner niche

Topic Locked

This topic has been locked by a moderator. New replies are not allowed.