Printable View
Commenting.... yep it's really a sucks thing in program.. bt we have to do it anyway..
I ussually write comments after i finished my program.. ussually i put a liitle descriptions of my program in points.. and put about me (like name, date it finished, or sometimes the developments of the program.)
and in the program itself i put it just in the main part only (which really need any).... and so far i finds it really helpful for me.... I hope you agree :)
Hmm,
When I am commenting, I follow no rule or procedure really, but it depends, on small even complex programs, {10 pages or less} I usually neglect comments, but when the program grows any larger than that I just comment about every screen. I just go /*trying to initiate password authentification, starting loop, allowing max of three tries, ending loop, starting array*/ I use notes that I understand, so I know where I am in my code, after all, once you write the code, you know how you did it all, so you know about where everything is. Well, that is just my 2 cents.
for me....
- just comments on the tricky/complex stuff such as loops, multithreading or complex calculation...
- and comments on function calling (to what function.. eg: API bla bla function).....
- and lastly comments what da functions does and the passing in and out variables... on every function...
- sometimes and manytimes i do lost in my codes... hehehe... then i print out all of them... it make me easier to understand after i print all of them.... try it out.. maybe works for u..
The thing I hate the most about commenting is when you forget to seperate your comments from the program code and wonder why the thing doesn't work anymore.......
Has it happened to only me, or has it happened to others?
Quote from some guy: "Why comment, the code was hard to write, it should be hard to read!"
Seriously, commenting is very important... Some members here have been saying that they don't bother commenting since they're the only one coding the project, or even they only coder in the company. While it might provide *some* job security when you're the only one who can understand the code, that excuse dosen't last long... What's more, think about the poor guys who'll have to maintain the code later... That guy might even be you... Will you remeber what that twisted algo. does in 2, 5, 10 years??? Think about the life expectency of your program: who would have tought that programs coded in the 70's would still be around in 2000, and have to be patched in 97-98-99 cuz of the y2k bug? The biggest cost of information systems is maintenance...
As for commenting strategies:
-First of all, a single fonction should do ONE and only one thing and do it well... That forces you to have well structured code that's easy to understand and requires less commenting.
-Second, name your variables appropriately. You should have documented/standardized coding practices.
-Thrid, if you need sooo much comments to make your code understandable, you're probably doing something wrong... Don't put useless/obvious comments like "x = y; // Sets x to y's value"... Also, get to the point with your comments: don't write a story...
Don't get me wrong, comments are good, just don't try to compensate bad code with alot of comments.
Personnaly, I sometimes do the following:
Comment BEFORE coding when coding complex algos: it helps you keep in mind what you're doing and what you want to do...
Comment WHY certain calls must be maid, or why it must be done a certain way.
Of course, comment APIs; Javadoc is great for that.
Well, that's my 2 cents...
(I might/probably have re-stated some of the previous posts.. Credit goes to the first to have said it ;)
Ammo
comments are usually simple enuf for me (i only have written small proggies at uni though)
most of them i put in after a few lines down from the code, they just say whats what really
nothing very in depth but enough to explain