To comment or not to comment? (not even a question...)

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

User avatar
Buddha443556
Forum Regular
Posts: 873
Joined: Fri Mar 19, 2004 1:51 pm

Post by Buddha443556 »

feyd wrote:Odd, I rarely commented in my Assembler code.
For me, it depended on the code. A printer driver required less commenting because it used a lot of documented values. On the other hand, a BigFloat library required extensive commenting because it was review and tested by others. A big warning comment in boot sector code about not touching do to critical timing issues was always useless ... but done anyway. Of course, when doing disassembly I find comments are extremely useful.

The biggest change I've seen is how important comments have become over the last thirty years, they've gone from source code to documentation to a tool of project management. Comments are now used as a form of information hiding - no one gets to look at the source code (although we all prefer it) unless they own it - only the API is available through some sort of Doc tool. Comments have become a integral part of project management by enforcing separation of responsibility. Of course, comments also have their down sided too now a days. Let one Public member get published in the API documentation and everybody will be using it before the end of the day causing nothing but problems down the road.
// Initialize variables
Guilty but that actually helps sometimes were source files are concatenated during building.
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post by RobertGonzalez »

Buddha443556 wrote:
// Initialize variables
Guilty but that actually helps sometimes were source files are concatenated during building.
I remember reading that comment in the original Sitepoint thread and thinking 'What's wrong with that?' I do that all the time, typically in modules or includes where the var will be referenced later but initialized there.
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Post by alex.barylski »

Everah wrote:
Buddha443556 wrote:
// Initialize variables
Guilty but that actually helps sometimes were source files are concatenated during building.
I remember reading that comment in the original Sitepoint thread and thinking 'What's wrong with that?' I do that all the time, typically in modules or includes where the var will be referenced later but initialized there.
Nothing wrong with it I guess, just redundant in high level languages.

If you structure your code (at least I do) when vars are set to ZERO or NULL or whatever at the beginning it's pretty obvious what is happening. It adds noise to your source code I guess, at least it bugs me. :P
User avatar
RobertGonzalez
Site Administrator
Posts: 14293
Joined: Tue Sep 09, 2003 6:04 pm
Location: Fremont, CA, USA

Post by RobertGonzalez »

I guess am I a pretty low level kinda guy ;).
Post Reply