Page 2 of 2

Posted: Thu Nov 10, 2005 6:12 pm
by s.dot
I have always gotten into the habbit of commenting my code. For me though, if the code is ugly, i feel like it's not done right =/

So I always use comments like this, I feel it is the prettiest :)

Code: Select all

/* this block of code does this */
and in the case that that kind of comment actually does span multiple lines, I do it like this

Code: Select all

/*
 * This is line one of my comment
 * and this is line two
 * and this is line three
 */

Posted: Thu Nov 10, 2005 8:25 pm
by McGruff
redmonkey wrote:The comments only get out of sync if you don't update them, if you don't update your test cases then they too will become out of sync, essentially they wont lie, they just won't work.
Sure but - ideally - you never walk away from a red bar. The idea of regression testing is that you always keep the app in a working state. And the red bar will explicitly tell you that the tests are out of sync.
redmonkey wrote:I run test scripts (not unit tests) which test the functionality of my code...
OK I was thinking specifically about unit tests; I don't know what sort of testing scripts you have. If you check out the unit testing forum you'll find some examples of the kind of thing i was talking about.

Posted: Thu Nov 10, 2005 9:54 pm
by dallasx
When I was a computer science major the department made code commenting worth 40% of any assignment's grade for any class. So, as anyone would climb through the slew of classes, commenting became a very nitty gritty thing. I hated it with a passion THEN... but now, it's probably one of the best coding techniques I've gotten used to. Especially with test scripts and stuff, something I'd come back to later (who knows when), sure makes it easy to figure out what the heck I was doing.

In the business sector I really understood how important it is. I understand that very small companies that are hired to create a backend to a website would want to make it hard to read code for the sake of future business. Their worst fear is someone like me, in the internal webmaster. I spent a couple of weeks with a book of each script and web page printed out, figuring out the logic and the structure. While scanning through a total of about 20,000 lines, I was saying to myself, "God, I wish this was commented."

In my opinion, I think every program/script should be commented.

Posted: Thu Nov 10, 2005 11:49 pm
by mickd
i normally don’t comment my code only because I’m the only one viewing my code and normally I’m only mucking around with code (and i tend to remember what every piece of code is doing (as long as i wrote it). at least so far i have).

another reason is because i feel as if it makes it more messy with my grammatically incorrect sentences all over my code.

Posted: Fri Nov 11, 2005 1:04 am
by n00b Saibot
mickd wrote:i normally don’t comment my code only because I’m the only one viewing my code and normally I’m only mucking around with code (and i tend to remember what every piece of code is doing (as long as i wrote it). at least so far i have).
I would say I'm almost the same way except for the fact I comment the code sparsely meaning where it would seem a little confusing to follow the code flow. Most of the time, code I write is simple enough that a competent developer can follow (newb not allowed to view my code :twisted: ). Also, I totally agree on wise-naming your vars, functions & classes... In that case, they provide good comments themselves.

Posted: Fri Nov 11, 2005 3:39 am
by Maugrim_The_Reaper
Strange... Has anyone tried suggesting commenting is a waste of time? ;) Thought not...

I tend to comment quite heavily, unless what the code is doing is extremely obvious from the outset. Unit tests do form a source of documentations - all those assertions lay out a classes expected behaviour in a lot of detail.