Spock's Brain and rem

[+Random Terrain]

I add as many comments as I can, but there are solutions to problems that pop in my head that I only understand for a brief time. I can't do outlines or flowcharts or comments at the time because the solution will leave my mind if I try to explain it, plus, I have a limited amount of time before the solution disappears so I just have to quickly type out the code. It always reminds me of the following part from the Star Trek: TOS episode called Spock's Brain where McCoy gets increased surgical knowledge to restore Spock's Brain, but that knowledge fades away before he can finish:

youtu.be/2zKDQfVbWqc?t=2m37s
http://www.youtube.com/watch?v=2zKDQfVbWqc&rel=0?t=2m37s
(Jump to 2:37.)

I usually have sections of code that I don't completely understand. Do I need to spend days trying to add detailed comments to those sections or is it good enough to have general remarks?

[SeaGtGruff]

I add as many comments as I can, but there are solutions to problems that pop in my head that I only understand for a brief time. I can't do outlines or flowcharts or comments at the time because the solution will leave my mind if I try to explain it, plus, I have a limited amount of time before the solution disappears so I just have to quickly type out the code. It always reminds me of the following part from the Star Trek: TOS episode called Spock's Brain where McCoy gets increased surgical knowledge to restore Spock's Brain, but that knowledge fades away before he can finish:

 

http://www.youtube.com/watch?v=rc6G3j0zViE

 

 

I usually have sections of code that I don't completely understand. Do I need to spend days trying to add detailed comments to those sections or is it good enough to have general remarks?

That's entirely up to you. Generally speaking, it can be better to have too many comments than too few, but it depends on a number of factors:

 

(1) How difficult is it to figure out what the code's doing-- looking at just the code, with no comments whatsoever? If you use meaningful names for your variables, constants, routines, and functions, and avoid using statements that are overly complicated, then most of your code might be more or less self-explanatory or self-evident.

 

(2) Will you be the only person who sees the code, or is it likely that other people will also be looking at your code? If no one besides you will ever look at it, then you don't need to explain your flow of thought. But if you expect that other people will be looking at your code, or that you might look at it at a later date without being able to remember what was in your head at the time, then you might want to use comments to record your train of thought.

 

(3) If you are writing code that other people will be looking at, then what kind of target audience are you writing for? If you're writing code examples for beginning programmers, then you might want to use more comments (and more verbose comments) than if you're writing routines that experienced programmers will be looking at.

 

(4) How important is it to you to ensure that anyone looking at your code will be able to quickly and easily figure out what it's doing, without having to analyze it in detail first? Some programmers want to be sure that anyone can understand their code, whereas other programmers might take a perverse sort of pleasure in using tightly-coded routines and obscure logic that will be difficult for other people to decipher (perhaps as a way of "protecting" their code from "prying eyes").

 

(5) Do your comments add to the program in a helpful way by explaining what the code is trying to accomplish, or do they detract from the program in a distracting way by simply describing what self-evident code is doing? For example, it would be more helpful to add a comment that says "turn on video blanking" than one that says "set VBLANK to 2."

 

(6) Are any portions of your code copied from or modeled after code that you saw in programs that other people wrote; and if so, do you want to acknowledge those sources?

 

Michael

[+Random Terrain]

Thanks. I got as detailed as I could today with Tone Toy 2008, so I think it's ready to show to the public. Now I need to create the instructions, screenshots, and video. I hoped to post Tone Toy 2008 tomorrow, but it will probably take an extra day just to make the video.