a couple points i can give you, and have learned the hard way

functions in any language should perform ONE task and ONE task only, even if the function ends up only being 2, 3 or 4 lines long, the more you separate each task into functions the more re-usable they are. if the functionality of the function can't be described in one line it's probably doing too much

second, avoid hard-coding values for computations in functions, unless the value is a constant value that never changes, instead pass the values into the functions as arguments, this way the function can be re-used with a different data set, if the value changes, but infrequently, design a config file so you can change the values without re-compiling (if using a compiled language) or having to dig too far into the code if using an interpreted language

third, give variables and functions meaningful names, yes you can use X,Y,Z,variable1,variabl2 etc.. but remember, you might not be the next person to look at the code, not to mention the more complex the code gets the harder it becomes to keep track of variable names.

forth, optional, but if your task is really, really big, then segment the program into logically arranged files.

1 members found this post helpful.

In a "real" programming shop, one starts with a detailed program specification. Thus the "explanation" is already written. The coder's task is to implement the specification, and the comments are, usually, references to or extracts from the specification document. Yes, the comment were maintained by the coders.As I've gotten older, I've found it really helps to have good comments in old code. Even code I've written solely for myself. (I don't think my coding abilities are fading, but my wife sometimes finds me "forgetful.)
Well, if you start with a good specification, "augmentation" is somewhat redundant. On the other hand, note my comment about a program to extract the comments as program documentation. I think (but haven't actually looked) that the Linux kernel documentation is generated in that fashion.

I don't think maintaining the comments needs to be difficult if you keep your functions "single-purpose."

1 members found this post helpful.

that depends on just how detailed you want your comments to be, some functions are rather self explanatory and need only a simple description of what the function does, what the arguments are supposed to be, and what the return value is, other times you might have to comment individual blocks or lines of code within functions to remind me what that particular line/block does within a larger function

yeah commenting can be a bit of a hassle, but coming back even after a hiatus of even a few weeks code you wrote can look foreign to you and commenting will save the hassle of having to read the code to figure out what's going on.

Good pointers guys. I'm really learning a lot here, thanks.
Question though. How much usage of function/subs do you use. Depending on who I was talking to, people would run their program differently. Some would have all the control of it in the "main" (not to be confused with C main) program and have all the tasks done in subs/func while others would only use the "main" program to call a func/sub that would run the program. Does anyone have any comments on good practices with that?
Thanks
RzITex

Too many comments often mean poorly written code.

E.g. unclear variable names.

The goal is to make code self-explanatory. The exceptions are, for example, work-arounds for bugs, some empirical formulas/coefficients, name of the algorithm used, especially, if it's not widely known algorithm.

Also, comments explaining how this piece of SW interacts with other pieces/processes and the decisions made to ensure the correct interaction. E.g. comments on all kinds of timeouts, number of stop-bits (yes, one might need 1.5 stop-bits).

imho you would use the main function to do initial tasks and tie the other functions togeather, having an intermediate function seems extranious, but i'm sure someone will post a reply as to why it isn't

+1 to Frieza's comment, mind you I have found that a few python folk use __main__ as a redirector - it doesn't seem to do a great deal.

I try to write C/C++ programs to be front-end independent (e.g. as an .so), then write a command-line implementation that might easily be replaced by a GUI front-end without having to restructure the parts that do the actual work.
Kevin Barry