(no subject)

[hyuri]

need to start commenting—and documenting!—my code properly. at least I’ve developed the habit of writing understandable code. at least to me. unlike my notes. ¬_¬

Comments

[science-vixen.livejournal.com]

need to start commenting -and documenting!-my code properly

Yes, another programmer sees the light, Hallelujah/Goddess be praised/other.....(*)!
or something to that order.

*) Please select the exclamation. if the correct exclamationisn't present, please insert on the dotted line.

[hyuri.livejournal.com]

My big problem is quickly and concisely explaining “what the hell is going on here?” ^^;;; And especially the function/accessor comments that pop up in VS as a quickie reference, since I always try to make those “sound” like the existing ones.

[science-vixen.livejournal.com]

The trick I leaned to do is to sort my comments as though they were chapters numbers and all

like:

[start code]
/**************************************************************
** program    : [program name]
** Author     : science_vixen
** Purpose    : [the function of the program in a nutshell]
** Parameters : [parameter meanings]
**-------------------------------------------------------------
** Maintenance
** Version | date     | Author | Reason
**-------------------------------------------------------------
** 0.1     | 20041102 | SV     | Initial code.
**************************************************************/

[declarations]

/* Comment summary */
/* 1. Start program */
/* 2. start [whatever] loop */
/* 2.1. Action in loop */
/* 2.2. Call outside function */
/* 2.3. end inside loop */
/* 3. end loop */
/* 4. more thingies */
/* 5. end program */

/* 1. Start program */
[program code]
/* 2. start [whatever] loop */
for x in Y loop
  /* 2.1. loop started */
  [program code]
  /* 2.2. Call outside function */
  [program code]
  /* 2.3. end inside loop */
end loop;
/* 3. end loop */
[program code]
/* 4. more thingies */
[program code]
/* 5. end program */
[end code]

[science-vixen.livejournal.com]

The clue to this is that you can actually plan your code beforehand, figure out that calls what, and which parameters you need before even having to decide wihich language to use.
Just list all your chapters in order, and then fill in the space in between with the code.
If you like you can use replace the comments with a variable.

just use a variable which updates with the status where you are in the program. (don't forget to comment in that this variable is your comment!).

then if you need a popup, you can use a stanard function which uses this variable, thus ensuring that your popups all have the same functionality.