Printable View
So this isn't sec related...but i expect a lot of you have opinions...
what are your strategies for commenting code...i find my strategy sucks...i never seem to "have the time" to do it...but gah...what a pain in the butt to go back without comments...do you comment at all...do you do it on the fly or after you've completed a module/procedure/whatever...
I put in non-specific comments in my code.... Just saying this is this, thta is that and if you change this or that then this will happen to that... I hope someone gets that :confused:
sure i get it...in a non-specific kind of way.... :p
all my code is javadoc friendly
I always try to make my functions small and easy to understand when reading the code... But I still add comments at the start of each function explaining what they do and through out the function what is happening... I don't comment normal if-sentences but often things as loops. Things which might not be to easy to understand. My main function/program (whatever u wanna call it) is then just a listing of all other functions (of course)... I explain most of my code by using logical var-names etc....
I've generally got a comment for each function, rarely I'll have two or three if the function does something complex.
I do not add comments, until I get lost in my own code :D
Then I start to add comments in specific places, like traffic polices...
:hiphop: :smokes:
I put comments as I go, to explain what certain tags or variables are for/do what. But if I get into a coding spurt, I tend to leave them out.....
It usually depends what/who I am coding for.....
i comment as i go. my basic rule of thumb is that if i cant immeadiatly understand what a loop or whatever is doing add a comment. also i always have a comment before each function, and comments at the end of nested loops/if statements to keep it as clear as possible.
Well, I always talk to myself and make comments when I am coding. Maybe thats the reason my office mate won't let me start up a compiler any more :(
The basic rule I follow is, if it takes me longer than ten seconds to figure out what a section of code is doing, it needs a comment. Maintaining code is hard enough without having to waste time reading every line of code just to understand what you're maintaining. I find the best way of "commenting" code is to write code that documents itself. This means using long_descriptive_ variable/function names and using good programming style. I tend to comment as I go while the code is still fresh in my mind but I also reread the code later and if I look at something and go "what the hell did I do there?" then in goes a comment.
All my programs start with a lengthy comment that describes the file, it's function, version, last revision, author(s) and anything else that other coders need to know. All functions are commented with a purpose, pre and post conditions. It's also handy to include the date and person who made a certain revision to a line of code (that's if you're not using CVS or some other similar software). So you know who to blame ;).
I think I would probably go with:
1. If making a public API (i.e. for anyone other than yourself, even if it's only internally to the project!), document each public method / function etc, if using Java, C#, Perl etc (which have their own built-in documentation facility), use that, otherwise create a sensible standard and follow it.
2. Most functions should be small enough that they don't require many comments inline in the code.
3. Any meaty functions,
a. Write the function entirely using pseudo-code
b. Write the proper code and leave the pseduo code in as comments.
4. Call methods, variables etc sensible names if there's any chance they could be confused. using "x" as a local variable in a 5 line function is ok, using x as a global variable or public property isn't !
Anyway it works for me.
I'm glad this was brought up. We should all be using standards when we write code :).Quote:
If making a public API (i.e. for anyone other than yourself, even if it's only internally to the project!), document each public method / function etc, if using Java, C#, Perl etc (which have their own built-in documentation facility), use that, otherwise create a sensible standard and follow it.
I usually have more comments then actual code. It makes it a lot easier for your friends to help you debug your code.
I'm terrible when it comes to commenting. I only seem to do it when I am trying to figure something out. If it is some I use often enough, I never comment it.
Same here. Except, I usually comment what a specific variable is for and at the start of a particularly long function.Quote:
I do not add comments, until I get lost in my own code
Then I start to add comments in specific places, like traffic polices...
Man, what the heck is commenting code good for? (This is of course my April Fools Joke)
Actually, I rarely comment my own programs (I'm the only one at the office who knows how to write, so they are all 100% my own creation), because I figure...if I can't figure out what it does...then it probably shouldn't be in there.
There was a site out there a few months back (maybe a year, who knows) that had a great joke article on how to make your code so complex that you're the only one who knows what it does...equals job security.
Unfortunately, I generally only comment code when I come back to it a second time to modify somthing. I start looking around, trying to figure out what I had done before, then I comment it as I figure it out. I keep telling myself that I need to start commenting the first time around, but for some reason, I don't listen.
commenting is very easy and should be done as you code.It's like the no: 1 rule of proper
codeing style,you should always comment because at the time while you'r codeing it might
seem to you that everything is understandable but two or three days later that same code wont look
so clear to you ,so always comment your code it makes it easy for you and also makes it easy for anyone that might have to modify your code later on.
crimina1
I dont think i have ever actually use comments in my programs, after all if you program the whole stuff for yourself you really dont need comments except for an occasional one or two or else if you have coded 1000s of lines of complex/confusing statements.
On the otherhand while programming for others esp some new programmer i try to make it as simple as possible by commenting as much as i can.
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